API reference/POST /v1/bookings/{hold_id}/confirm

POST /v1/bookings/{hold_id}/confirm

requires akidempotentaudited decision

Confirm a hold, promoting it to a committed booking.

Request

POST /v1/bookings/{hold_id}/confirm HTTP/1.1
Authorization: Bearer ak_01HX7QQM…
Content-Type: application/json

{
  "start": "2026-06-01T14:00:00Z",
  "end": "2026-06-01T14:45:00Z",
  "title": "Demo call with Acme",
  "description": "…",
  "attendees": [{ "email": "guest@example.com", "name": "Jane Guest" }]
}

startreq

string:date-timeUTC date-time string.

endreq

string:date-timeUTC date-time string.

titlereq

stringMust not be empty.

description

string

attendees

object[]Contains email, displayName.

attendees[].emailreq

string:emailEmail address.

attendees[].displayName

string

Response

Returns 200 OK with the response body below. Successful booking arbitration writes an audit row you can query through the audit log.

200 OK · example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "booking_id":            "3f0659cf-bb67-4947-99de-7b18cc77153a",
  "correlation_id":        "ea752c87-0969-4a15-96b7-46f1badb2359",
  "start":                 "2026-06-01T14:00:00.000Z",
  "end":                   "2026-06-01T14:45:00.000Z",
  "title":                 "Demo call with Acme",
  "description":           null,
  "calendar_type":         "work",
  "attendees":             [{ "email": "guest@example.com" }],
  "status":                "committed",
  "displaced_count":       1,
  "pending_notifications": []
}

// displaced_count and displaced_bookings are only present when the
// booking preempted one or more lower-priority committed bookings.

Errors

Code	Description
`400`	Validation failed — body is malformed or missing required fields.
`401`	Missing or invalid API key. Send the raw key as a Bearer token in the Authorization header.
`403`	Agent does not hold the permission scope required for this call (e.g. preempt on a higher-priority class).
`404`	Calendar owner or booking id not found.
`409`	Conflict — the requested slot was already committed at higher priority. Inspect alternatives[] in the response body.
`410`	Default Response
`422`	Validation error — the request body is structurally valid but semantically rejected. Common causes: earliest_start is in the past (PAST_TIME), the window is shorter than the requested duration (WINDOW_TOO_NARROW), the chosen slot is outside the hold window (SLOT_OUTSIDE_HOLD), or an idempotency key was reused with a different body (IDEMPOTENCY_CONFLICT). The error code field names the specific cause.