Guests

Push guests into a property (write-only; grants no read of guest data).

Create or update a guest at a property

post

Requires guests:write. Push a guest into the Guests section — for a CRM/PMS/booking integration to feed guests in. Write-only: this scope grants no read of guest data. Identity is (property, email), so a repeat push of the same email to the same property updates that guest (200) rather than creating a duplicate (201 on first create). Include an optional reservation to upsert the guest's stay in the same call (identity (property, reservation.external_id)), so you can build audiences on stay status, booking channel, and recently-ended stays. A guest erased under GDPR is never repopulated (409).

Authorizations

bearerAuth

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Body

application/json

A guest to create or update at one property. Identity is (property, email): a repeat push of the same email to the same property updates that guest rather than creating a duplicate. Optionally include a reservation to upsert the guest's stay in the same call.

property_idstring · uuidOptional

The property (leaf node) to attach the guest to. Optional when the key is bound to a single property; required when the key is bound to a group. Must be a property within the key's node scope.

emailstring · email · max: 320Required

Required — normalized (trimmed + lower-cased) and used as the dedupe key.

salutationstring · max: 50Optional

first_namestring · max: 200Optional

last_namestring · max: 200Optional

phonestring · max: 40Optional

country_codestring · min: 2 · max: 2Optional

ISO 3166-1 alpha-2 (e.g. DE).

language_codestring · max: 5Optional

e.g. de or de-DE.

marketing_consentbooleanOptional

When set, records invitation-email consent. An explicit prior withdrawal is never overridden by a grant (GDPR).

Responses

200

Existing guest updated.

application/json

A guest record as stored. source is api for guests created through this endpoint.

idstring · uuidOptional

property_idstring · uuidOptional

sourcestringOptionalExample: api

emailstring · nullableOptional

salutationstring · nullableOptional

first_namestring · nullableOptional

last_namestring · nullableOptional

phonestring · nullableOptional

country_codestring · nullableOptional

language_codestring · nullableOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

201

Guest created.

application/json

400

Invalid request.

application/json

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

409

The guest has been erased (GDPR) and can no longer be updated.

application/json

422

property_id is missing, out of scope, or not a property (leaf) node.

application/json

429

Rate limit exceeded. Honour the Retry-After header.

application/json

post/guests

HTTPcURLJavaScriptPython

POST /api/v4/guests HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 284

{
  "property_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "[e-mail]",
  "first_name": "Jane",
  "last_name": "Doe",
  "marketing_consent": true,
  "reservation": {
    "external_id": "BK-1001",
    "status": "checked_out",
    "check_in": "2026-08-01",
    "check_out": "2026-08-04",
    "channel": "booking.com"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "property_id": "123e4567-e89b-12d3-a456-426614174000",
  "source": "api",
  "email": null,
  "salutation": null,
  "first_name": null,
  "last_name": null,
  "phone": null,
  "country_code": null,
  "language_code": null,
  "created_at": "2026-08-11T20:23:26.110Z",
  "updated_at": "2026-08-11T20:23:26.110Z",
  "reservation": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "external_id": "text",
    "status": "booked",
    "raw_status": null,
    "check_in": null,
    "check_out": null,
    "checked_in_at": null,
    "checked_out_at": null,
    "channel": null,
    "created_at": "2026-08-11T20:23:26.110Z",
    "updated_at": "2026-08-11T20:23:26.110Z"
  }
}