Developers
Sending your events to WhenIs.it
How an organization's own system publishes its programme here: the import format, the push endpoint and its keys, and the feeds we read.
Two ways in
An organization's events can reach WhenIs.it without anybody typing them in. Its owner or an admin asks for a source on the organization's Automation page, and once our team has approved it, the source publishes as the organization by itself:
- A feed we read. Give us an address and we read it every few hours: an iCalendar file (
.ics, the address a calendar app subscribes to), or a page whose events carry schema.orgEventmarkup in JSON-LD. See Feeds we read. - Your system sends them. Your developer posts your programme to us in the format below whenever it changes, with an API key made on the Automation page. The rest of this page is for them.
Either way, what a source sends is your programme: an event it stops listing is taken off the site while it is still to come, and changing an event at the source changes it here. Fields a source sends are edited at the source, not on WhenIs.it.
Sending a document
Post the document to /$import on the site, with the source's API key as a bearer token:
curl -X POST https://whenis.it/$import \
-H "Authorization: Bearer $WHENISIT_KEY" \
-H "Content-Type: application/json" \
--data-binary @programme.json
- The key is shown once, when it is made; we keep only a hash of it. Make one per system that sends, revoke one that leaked, and make another.
- A key works while the person who made it is an owner or admin of the organization and neither their account nor the organization is suspended. When they leave, make a new key.
- The body may be gzipped (
Content-Encoding: gzip), and may be up to 5 MB once unpacked. ?dryRun=truereads and checks the document, says what it would do, and changes nothing.
The answer is JSON: the run's runId, its status (succeeded, succeededWithWarnings or failed), its counts (events created, updated, unchanged, staged, retracted, removed) and, when it failed, an error.
| Status | Means |
|---|---|
200 | Imported, or checked on a dry run. |
400 | The document is not one: not JSON, not format version 1, or a list where a value belongs. |
401 | No key, or not a key that works. |
403 | The key's maker may no longer act for the organization. |
409 | The source is not running: waiting for approval, paused, declined, or stopped after making far more than usual in a day. Or another document is being imported into it right now; try again shortly. |
413 | The body is over 5 MB. |
422 | The run failed; error says why. Nothing was changed. |
429 | Too many documents this hour; slow down. |
Your whole programme, or part of it
A document is your whole upcoming programme unless it says otherwise: an event it no longer lists is taken off the site, if it has not happened yet. A run that would take off more than a quarter of what the source has (and more than ten events) fails instead, so a document that is empty by mistake changes nothing.
To send only what changed, mark the document "partial": true. Nothing missing from it is taken off; list the events to take off in removedEventIds instead. An id taken off and later sent again comes back as the same event.
{
"formatVersion": 1,
"partial": true,
"events": [ { "id": "2026-11-20-quiz", "name": "Quiz night", "startTime": "2026-11-20T19:00:00", "venueId": "main" } ],
"removedEventIds": ["2026-11-13-quiz"]
}
A whole document can also leave out events that have not changed since you last sent them: list their ids in keptEventIds and they stay on the site exactly as they are. A kept id we have no event for is reported in the run's log; send that event in full.
The document
JSON, UTF-8, with camelCase field names. Fields we do not know are ignored. Venues, performers and tags are listed once and events point at them by id; a venue can also be given on the event itself.
| Field | Notes |
|---|---|
formatVersion | Required, exactly 1. |
defaultTimeZone | An IANA zone (Europe/Stockholm) for times written without an offset. Without it, the zone you gave when you asked for the source. |
partial, removedEventIds, keptEventIds | See above. |
venues, performers, tags | The catalogue events point at. |
events | The events. |
An event:
| Field | Notes |
|---|---|
id | Required, and the same every time you send the event: it is how we know it is the one we have. At most 50 characters. |
name | Required. |
startTime, endTime | ISO 8601. With an offset (2026-11-20T19:00:00+01:00) it is that moment; without one, a time on the event's, its venue's or the document's zone. |
startDate, endDate | For an event with dates and no times: 2026-11-20. |
timeZone | The event's own IANA zone. |
description | Plain text. |
ticketUrl, infoUrl, imageUrl | Absolute http or https addresses. |
status | scheduled, postponed, rescheduled or cancelled. |
soldOut | true when tickets are gone. |
attendanceMode, onlineUrl | inPerson, online or both, and the link to join. |
venueId or venue | A venue from venues, or one given here. An event with no place goes to your source's default venue, if it has one, and waits otherwise. |
performerIds, tagIds | Ids from performers and tags. |
A venue has an id, a name, an address, a postalCode, a timeZone, a city (name and countryCode) and a coordinate (latitude, longitude). A performer has an id, a name and a url; a tag an id and a name.
An event that is short of something waits rather than being refused: no name, no time we can read, or no place we know. The Automation page lists what waits and why, and it is imported once a document gives what was missing.
A complete document
{
"formatVersion": 1,
"defaultTimeZone": "Europe/Stockholm",
"venues": [
{ "id": "main", "name": "Folkets Hus", "address": "Slaggatan 11", "city": { "name": "Falun", "countryCode": "SE" } }
],
"performers": [ { "id": "hazelius", "name": "Esbjörn Hazelius" } ],
"events": [
{
"id": "2026-11-20-folk",
"name": "Folk night: Esbjörn Hazelius",
"startTime": "2026-11-20T19:30:00",
"endTime": "2026-11-20T23:00:00",
"ticketUrl": "https://example.com/tickets/2026-11-20",
"venueId": "main",
"performerIds": ["hazelius"]
},
{ "id": "2026-12-05-market", "name": "Christmas market", "startDate": "2026-12-05", "endDate": "2026-12-06", "venueId": "main" }
]
}
Feeds we read
- iCalendar: every event still to come within a year, a repeating one as each of its dates (its exceptions left out, a moved date as it was moved). Its
UIDis its id, so keep it the same.LOCATIONis the place (the part before the first comma its name),STATUS:CANCELLEDcancels it, andURLis its page. Awebcal://address works. - A page with JSON-LD: every
<script type="application/ld+json">on it, events of any schema.orgEventtype, in a@graphor anEventSeriestoo. Its@id, else itsurl, is its id. Itslocation,offers,eventStatus,eventAttendanceMode,imageandperformerare read as schema.org describes them.
We read an address only if it is a public one, and at most 5 MB of it. Preview, on the Automation page, reads it now and shows what it would publish.