# Create and update waitlist entries

Create guests, find entries and apply supported lifecycle changes safely.

## Create a guest

POST /waitlist/entries requires queueId, fullName and Idempotency-Key. Include serviceTypeId or public customData when required by the selected line. The creation response returns entry.id, guestId and bookingId, which is null for a walk-in.

An optional externalReference connects an entry to your system. Use an identifier that contains no personal information. Look up an exact reference with GET /waitlist/entries?externalReference=YOUR_REFERENCE; do not use names or phone numbers as a search interface. Normal guest allowances and accounting still apply.

## Read and edit an entry

GET /waitlist/entries/{entryId} returns the current entry and version. Guest name, phone details and custom-field values need guest:read. PATCH the same path to change explicitly supported guest fields, with expectedVersion and a stable Idempotency-Key.

A version conflict means the entry changed after you read it. Fetch its current state and decide whether your action still applies. Do not silently overwrite a newer edit.

## Move a guest through the line

Statuses are waiting, ready, confirmed, in_service, completed, cancelled and no_show. The domain rules determine which transitions are valid from the current state. PATCH /waitlist/entries/{entryId}/status with status, expectedStatus and the version you just read.

Retention-driven archiving is separate from customer status commands. An API integration cannot use status updates to delete guests or override retention.

```json
{"status":"ready","expectedStatus":"waiting","expectedVersion":1}
```

## Record consent before requesting SMS

A phone number or an automation connection is not SMS consent. Include smsConsent only after the guest affirmatively agrees to the applicable disclosure. Record the collection source, UTC consent timestamp and disclosure version. Omit smsConsent when permission was not collected; the entry uses the permitted non-SMS workflow.

Plan eligibility, opt-outs and existing messaging restrictions still apply. Consent does not guarantee delivery, and the public API does not expose raw SMS sending or internal SMS templates.

```json
{"smsConsent":{"source":"test-check-in-form","consentedAt":"2026-09-26T09:00:00Z","disclosureVersion":"your-reviewed-disclosure-v1"}}
```