Docs
API referenceBookings

Create a booking

Preview· P9
POST/bookings

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.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers 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 modeAs 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:write

Header Parameters

Idempotency-Key*string

A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the original response instead of acting twice. While the first request is still running, a retry returns conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/bookings" \  -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64" \  -H "Content-Type: application/json" \  -d '{    "booking_type_id": "btype_01kn44arm0eya81713cpbnfbpq",    "start_at": "2026-10-16T10:00:00Z",    "attendee": {      "name": "Ama Owusu",      "phone": "+233241234567",      "email": "ama@coastline.example",      "company": "Coastline Consult"    },    "custom_fields": {}  }'

{  "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"}

List bookings GET

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

Get a booking GET

Returns one booking, including the linked visit for confirmed in-person bookings. **Scope:** `bookings:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.