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.org Event markup 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=true reads 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.

StatusMeans
200Imported, or checked on a dry run.
400The document is not one: not JSON, not format version 1, or a list where a value belongs.
401No key, or not a key that works.
403The key's maker may no longer act for the organization.
409The 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.
413The body is over 5 MB.
422The run failed; error says why. Nothing was changed.
429Too 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.

FieldNotes
formatVersionRequired, exactly 1.
defaultTimeZoneAn IANA zone (Europe/Stockholm) for times written without an offset. Without it, the zone you gave when you asked for the source.
partial, removedEventIds, keptEventIdsSee above.
venues, performers, tagsThe catalogue events point at.
eventsThe events.

An event:

FieldNotes
idRequired, and the same every time you send the event: it is how we know it is the one we have. At most 50 characters.
nameRequired.
startTime, endTimeISO 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, endDateFor an event with dates and no times: 2026-11-20.
timeZoneThe event's own IANA zone.
descriptionPlain text.
ticketUrl, infoUrl, imageUrlAbsolute http or https addresses.
statusscheduled, postponed, rescheduled or cancelled.
soldOuttrue when tickets are gone.
attendanceMode, onlineUrlinPerson, online or both, and the link to join.
venueId or venueA 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, tagIdsIds 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 UID is its id, so keep it the same. LOCATION is the place (the part before the first comma its name), STATUS:CANCELLED cancels it, and URL is its page. A webcal:// address works.
  • A page with JSON-LD: every <script type="application/ld+json"> on it, events of any schema.org Event type, in a @graph or an EventSeries too. Its @id, else its url, is its id. Its location, offers, eventStatus, eventAttendanceMode, image and performer are 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.