Events and bookings
Put a booking on the workspace’s Calendar straight from a website, or a meeting from a server. No backend of your own is required: a publishable token can post from browser JavaScript.
Read Authentication first for tokens, status codes and origin allowlisting.
POST /api/v1/events
Section titled “POST /api/v1/events”Creates an event. Requires the events:write scope.
POST https://api.erreos.com/api/v1/eventsAuthorization: Bearer erre_pk_...Content-Type: application/jsonFields
Section titled “Fields”startsAt is required, and so is a title or a name. Everything else is
optional.
| Field | Type | Max | Notes |
|---|---|---|---|
startsAt |
string | Required. ISO 8601 with an offset. See Send the offset. | |
title |
string | 200 | What the event is called. With none, the customer’s name is used. |
name |
string | 200 | The customer who booked. Required when you send email or phone. |
email |
string | 320 | The customer’s. |
phone |
string | 40 | The customer’s. |
endsAt |
string | ISO 8601 with an offset. Send this or durationMinutes, not both. |
|
durationMinutes |
integer | A whole number of minutes, 1 or more. With neither this nor endsAt, the event runs 60. |
|
kind |
string | "booking" (the default), "meeting" or "other". |
|
notes |
string | 5000 | Free text. Shown as the event’s description. |
location |
string | 300 | An address, a room or a link. |
assignee |
string | 320 | The email of the workspace member whose calendar it goes on. Secret tokens only. See Who gets it. |
externalId |
string | 200 | Your own id for this booking. See Retries. |
A field set to null is treated as if you had omitted it. A field this endpoint
does not list is rejected with unknown_field.
An event must end after it starts and can run for 7 days at most.
Request bodies are capped at 32 KB.
Responses
Section titled “Responses”Created:
{ "ok": true, "id": "k17d8k2m4n6p8q0r2s4t6u8v" }201 Created
Already existed, because you sent an externalId that was seen before:
{ "ok": true, "id": "k17d8k2m4n6p8q0r2s4t6u8v", "deduplicated": true }200 OK
A deduplicated request changes nothing. The first event is returned as it is. A second post does not move or rename it.
Errors of this endpoint
Section titled “Errors of this endpoint”All are 400. The shared ones (401, 403, 429, unknown_field,
field_too_long) are in Authentication.
| Code | Meaning |
|---|---|
invalid_time |
startsAt is missing, has no offset, is not a real date, ends before it starts or runs too long. Also durationMinutes that is not a whole number of 1 or more, or sent together with endsAt. |
title_required |
Neither title nor name was sent. |
name_required |
email or phone was sent with no name. |
invalid_field |
A field has the wrong type, or kind is not one of the three. |
unknown_assignee |
assignee is not the email of a member of this workspace. Nothing was written. |
assignee_not_allowed |
assignee was sent with a publishable token. Nothing was written. |
The snippet
Section titled “The snippet”<script> document.querySelector('#booking-form').addEventListener('submit', async (e) => { e.preventDefault(); const form = new FormData(e.target);
// The visitor picked a day and a time on their own clock. `toISOString()` // turns that into an instant with an offset (`Z`). const startsAt = new Date(`${form.get('date')}T${form.get('time')}`).toISOString();
const res = await fetch('https://api.erreos.com/api/v1/events', { method: 'POST', headers: { Authorization: 'Bearer erre_pk_...', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: form.get('name'), email: form.get('email'), phone: form.get('phone'), startsAt, durationMinutes: 45, notes: form.get('message'), externalId: e.target.dataset.bookingId }) });
if (!res.ok) { // The booking was NOT saved. Show the visitor an error and log this. console.error('ErreOS booking failed', res.status, await res.json()); return; } });</script>The same call with curl, from a server. It names an assignee, so it uses a
secret token:
curl -X POST https://api.erreos.com/api/v1/events \ -H "Authorization: Bearer erre_sk_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "email": "jane@example.com", "phone": "+1 555 0100", "startsAt": "2026-11-20T10:00:00-06:00", "durationMinutes": 45, "notes": "First visit. Gate code 4411.", "assignee": "ana@yourbusiness.com" }'Do not drop the !res.ok branch. A form that posts and ignores the response
looks like it works while losing every booking it fails to send.
Four things that catch people out
Section titled “Four things that catch people out”Send the offset
Section titled “Send the offset”"2026-11-20T10:00:00" is refused with invalid_time. With no offset it is ten
o’clock in a zone the server would have to guess, and a booking that lands an
hour off is worse than an error you see once. Send Z or an offset:
"2026-11-20T16:00:00Z", "2026-11-20T10:00:00-06:00".
A date that does not exist is refused the same way: 2026-02-31 and T24:00
are errors, not 3 March and the next morning.
In a browser, new Date(localDateAndTime).toISOString() reads the visitor’s own
clock and gives you the instant. If your business takes bookings on its own
clock whatever the visitor’s is, build the string with your business’s offset.
The time is not checked
Section titled “The time is not checked”This endpoint does not look at what is already on the calendar. Two bookings at ten are two events at ten. There is no availability endpoint: if your form offers slots, your form decides which are free.
Who gets it
Section titled “Who gets it”With an assignee, the event goes on that member’s calendar. The value is the
email they are a member with, in any letter case. An address that is not a
member’s is refused with unknown_assignee and nothing is saved. So is someone
with an account who was asked to join and has not answered yet.
assignee needs a secret token. A publishable token is visible in your
page’s source, so it may not name a person: a request that sends assignee
with one is refused with assignee_not_allowed. Post from the browser without
it, or post from your server with a secret token.
With no assignee, the event is on nobody’s calendar yet. The workspace’s
owners and admins see it on theirs and put a person on it.
Retries need an externalId
Section titled “Retries need an externalId”Without one, a retried request makes a second event. Generate an id once per
booking, not once per request, and send the same one on every attempt. The
second attempt answers 200 with "deduplicated": true and the first event’s
id.
What happens after a successful post
Section titled “What happens after a successful post”The event appears on the Calendar at once, as a booking with the customer’s
name, email and phone on it. No notification is sent and no contact is created:
if you also want the person in the CRM, post them to
/api/v1/contacts as well.