Skip to content

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.

Creates an event. Requires the events:write scope.

POST https://api.erreos.com/api/v1/events
Authorization: Bearer erre_pk_...
Content-Type: application/json

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.

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.

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.
<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:

Terminal window
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.

"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.

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.

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.

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.

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.