List bookings
/bookingsReturns bookings, newest first. Filter by booking type, host, status or start time.
Scope: bookings:read · Plan: Pro and Enterprise in live mode; every plan in test mode.
Send Authorization: Bearer <token> on every request. The token is one of:
| Prefix | What it is | Where it may be used |
|---|---|---|
agoo_sk_live_ | Secret key, live mode | Your servers only |
agoo_sk_test_ | Secret key, test mode | Your servers only |
agoo_pk_live_ | Publishable key, live mode | Browsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people. |
agoo_pk_test_ | Publishable key, test mode | As above, in test mode |
Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.
In: header
Scope: bookings:read
Query Parameters
How many items to return, from 1 to 100.
1 <= value <= 10025The next_cursor from the previous page. Leave it out for the first page.
length <= 512Only bookings of this booking type.
^btype_[0-7][0-9a-hjkmnp-tv-z]{25}$"btype_01kn44arm0eya81713cpbnfbpq"Only bookings with this host.
^person_[0-7][0-9a-hjkmnp-tv-z]{25}$"person_01kjsesxm0e4zbyvkr7bcfxbfg"Only bookings with this status.
Value in
- "pending"
- "confirmed"
- "declined"
- "expired"
- "cancelled"
Only bookings that start at or after this time.
date-timeOnly bookings that start before this time.
date-timeResponse Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/bookings?limit=25&start_after=2026-10-16T00%3A00%3A00Z&start_before=2026-10-17T00%3A00%3A00Z"{ "data": [ { "id": "booking_01m4dtqd00eq4rtc1jdsr1gr6z", "status": "confirmed", "booking_type_id": "btype_01kn44arm0eya81713cpbnfbpq", "host_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg", "start_at": "2026-10-16T10:00:00Z", "end_at": "2026-10-16T10:30:00Z", "time_zone": "Africa/Accra", "meeting_kind": "in_person", "site_id": "site_01kjpt3yw0fz0v414608h9x65s", "meeting_url": null, "address": null, "attendee": { "name": "Ama Owusu", "phone": "+233241234567", "email": "ama@coastline.example", "company": "Coastline Consult" }, "visit_id": "visit_01m4dtqdz8f59rarmdksqjprz9", "custom_fields": {}, "confirm_by": null, "confirmed_at": "2026-10-08T13:20:00Z", "declined_at": null, "decline_reason": null, "cancelled_at": null, "cancellation_reason": null, "created_at": "2026-10-08T13:20:00Z", "updated_at": "2026-10-08T13:20:00Z" } ], "next_cursor": null, "has_more": false}Get free slots GET
Returns the slots that can be booked for a booking type between two dates, after working hours, Ghana public holidays, buffers, minimum notice, daily caps and existing bookings are taken into account. A `pending` booking holds its slot until the host declines it or it expires. Slots are a snapshot: one can be taken before you book it, which returns `conflict`. The range covers whole days in `time_zone` and can span up to 31 days. **Scope:** `bookings:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode. **Publishable keys:** allowed for public booking types.
Create a booking POST
Books a slot from `GET /booking-types/{btype_id}/availability`. If the slot has been taken in the meantime, you get `conflict`; fetch availability again and offer another time. - If the booking type doesn't require host confirmation, the booking is `confirmed` straight away. Agoo confirms it to the attendee and the host, and sends reminders by your organisation's settings. - If it does (`requires_confirmation`), the booking starts as `pending` and holds its slot. Agoo tells the attendee their request was received and asks the host to confirm or decline it before `confirm_by`. See `POST /bookings/{booking_id}/confirm` and `/decline`. - Fires `booking.created` for every booking, with its `status`. - A confirmed `in_person` booking also creates an expected visit with a QR pass, so the attendee can check in on arrival. Its `visit_id` is set, and `visit.created` and `pass.sent` fire too. For a `pending` booking this happens when the host confirms it. - `custom_fields` are checked against the visit form for the booking type's `visit_type`. With a publishable key, they may contain only the fields in the booking type's `public_form`; a field your staff fill in returns `validation_failed` at `body.custom_fields.<key>`. - Leave `host_id` out to let Agoo pick a free host from the booking type's hosts. - A `booking_type_id` that isn't a booking type you can book (unknown, turned off, or private with a publishable key), or a `host_id` that isn't one of its hosts, returns `validation_failed`. **Scope:** `bookings:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode. **Publishable keys:** allowed for public booking types.