> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialtu.com/llms.txt > Use this file to discover all available pages before exploring further. # Add a client to the waiting list > Put a client on the waiting list for each named service. Idempotent: an open entry for the same (client, service) is updated with the preferences sent and returned with ``created: false``; a new one is ``created: true``. Always ``200`` on success. The client is identified by ``client_id`` OR ``phone`` (E.164) — phone-less contacts must be sent by ``client_id``. ## OpenAPI ````yaml POST /api/v2/public/calendar/waitlist/entries openapi: 3.1.0 info: title: Dialtu Public API version: '2.0' description: >- Programmatic access to your Dialtu account: schedule AI voice calls, create contacts, push leads into Salesflow pipelines, book calendar appointments and read WhatsApp conversation history. Every request is authenticated with an API key created in the dashboard under **Settings → API Keys**, sent as `Authorization: Bearer pk_...`. servers: - url: https://api.dialtu.com description: Production - url: https://api.stg.dialtu.com description: Staging security: - ApiKeyBearer: [] tags: - name: Calls description: Schedule outbound AI voice calls. - name: Clients description: Create contacts in your account. - name: Salesflow description: Push leads into a pipeline through an API input node. - name: Salesflow pipelines description: Read a pipeline's stages and add, move or remove clients. - name: Calendar description: Check bookable capacity, book appointments and manage waiting lists. - name: WhatsApp description: Read-only conversation history and transcripts. paths: /api/v2/public/calendar/waitlist/entries: post: tags: - Calendar summary: Add a client to the waiting list description: >- Put a client on the waiting list for each named service. Idempotent: an open entry for the same (client, service) is updated with the preferences sent and returned with ``created: false``; a new one is ``created: true``. Always ``200`` on success. The client is identified by ``client_id`` OR ``phone`` (E.164) — phone-less contacts must be sent by ``client_id``. operationId: createWaitlistEntries parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PublicWaitlistEntryCreateSchema' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicWaitlistEntryCreateResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' '401': description: Missing, malformed or revoked API key. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' examples: missing_header: summary: No Authorization header value: detail: Unauthorized invalid_key: summary: Unknown or revoked key value: detail: Invalid or expired API key. Please check your credentials. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' '422': description: The request did not match the documented schema. content: application/json: schema: $ref: '#/components/schemas/RequestValidationError' example: detail: - type: missing loc: - body - payload - phone_number msg: Field required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/PublicCalendarErrorResponse' security: - ApiKeyBearer: [] components: schemas: PublicWaitlistEntryCreateSchema: description: >- Body of ``POST /calendar/waitlist/entries``. Identify the client with EITHER ``client_id`` (a contact already in this workspace) OR ``phone`` (E.164; the contact is matched by phone or created with the given names/email). Name the services by ``service_ids`` or ``service_names``. ``waitlist_id`` is optional: left out, each service is routed to the active list that contains it. properties: client_id: anyOf: - type: integer - type: 'null' description: An existing contact's id title: Client Id phone: anyOf: - type: string - type: 'null' description: E.164 phone, e.g. +573001112233 (alternative to client_id) title: Phone first_name: anyOf: - maxLength: 100 type: string - type: 'null' description: Given name, used only when the contact is created. title: First Name last_name: anyOf: - maxLength: 100 type: string - type: 'null' description: Family name, used only when the contact is created. title: Last Name email: anyOf: - maxLength: 255 type: string - type: 'null' description: Email, used only when the contact is created. title: Email waitlist_id: anyOf: - type: integer - type: 'null' description: Target list; omitted → resolved per service title: Waitlist Id service_ids: anyOf: - items: type: integer type: array - type: 'null' description: Services by id title: Service Ids service_names: anyOf: - items: type: string type: array - type: 'null' description: Services by exact name (case-insensitive) title: Service Names priority: anyOf: - maximum: 3 minimum: 0 type: integer - type: 'null' description: 0 urgent, 1 high, 2 normal (default), 3 low title: Priority preferred_professional_id: anyOf: - type: integer - type: 'null' description: calendar_profile_id the client would rather wait for title: Preferred Professional Id earliest_date: anyOf: - type: string - type: 'null' description: YYYY-MM-DD title: Earliest Date latest_date: anyOf: - type: string - type: 'null' description: YYYY-MM-DD title: Latest Date time_preference: anyOf: - type: string - type: 'null' description: any | morning | afternoon | evening title: Time Preference notes: anyOf: - maxLength: 2000 type: string - type: 'null' description: Free text shown to the team on the entry. title: Notes title: PublicWaitlistEntryCreateSchema type: object PublicWaitlistEntryCreateResponse: description: |- Response for ``POST /calendar/waitlist/entries`` (always 200 on success: the call is an upsert). properties: status: const: success default: success description: Always `success`. title: Status type: string data: $ref: '#/components/schemas/PublicWaitlistEntryCreateDataSchema' description: Upsert result. required: - data title: PublicWaitlistEntryCreateResponse type: object PublicCalendarErrorResponse: description: Error envelope shared by every public calendar endpoint. properties: status: const: error default: error description: Always `error`. title: Status type: string error_code: description: Machine-readable error code; branch on this, never on `message`. title: Error Code type: string message: description: Human-readable explanation. title: Message type: string details: anyOf: - {} - type: 'null' description: Extra context, e.g. `valid_service_names` or the offending `field`. title: Details required: - error_code - message title: PublicCalendarErrorResponse type: object DetailErrorResponse: description: 'Plain error body: `{"detail": "..."}`. No `error_code` is included.' properties: detail: description: Human-readable reason for the failure. title: Detail type: string required: - detail title: DetailErrorResponse type: object RequestValidationError: title: RequestValidationError type: object description: >- Returned when the request body, query string or path could not be parsed against the documented schema. Fix the listed fields and retry. properties: detail: type: array title: Detail description: One entry per invalid field. items: $ref: '#/components/schemas/RequestValidationErrorItem' required: - detail PublicWaitlistEntryCreateDataSchema: description: Payload of the upsert response. properties: client_id: description: Client ID the entries belong to. title: Client Id type: integer client_created: description: True when the contact itself was created by this call title: Client Created type: boolean entries: description: One entry per requested service. items: $ref: '#/components/schemas/PublicWaitlistEntrySchema' title: Entries type: array required: - client_id - client_created title: PublicWaitlistEntryCreateDataSchema type: object RequestValidationErrorItem: title: RequestValidationErrorItem type: object properties: loc: type: array title: Loc description: >- Where the problem is: the first element is `body`, `query` or `path`, followed by the field path. items: anyOf: - type: string - type: integer msg: type: string title: Msg description: What is wrong with the value. type: type: string title: Type description: >- Machine-readable validation error type, e.g. `missing` or `int_parsing`. required: - loc - msg - type PublicWaitlistEntrySchema: description: One (client, service) row on a waiting list. properties: id: description: Entry ID (use it with *Remove a client from the waiting list*). title: Id type: integer waitlist_id: description: ID of the waiting list the entry sits on. title: Waitlist Id type: integer client: $ref: '#/components/schemas/PublicWaitlistClientSchema' description: The contact. service: $ref: '#/components/schemas/PublicWaitlistServiceSchema' description: The service waited for. status: description: waiting | queued | booked | removed | expired title: Status type: string priority: description: 0 urgent, 1 high, 2 normal, 3 low. title: Priority type: integer position: anyOf: - type: integer - type: 'null' description: >- 1-based place in the service's rotation; null when not in rotation (queued, snoozed, flagged or resolved) title: Position queue_attempts: default: 0 description: How many times a seat has been offered to this entry. title: Queue Attempts type: integer flagged_for_review: default: false description: True when the entry needs a person's attention. title: Flagged For Review type: boolean snooze_until: anyOf: - type: string - type: 'null' description: ISO 8601 UTC instant the snooze ends, if snoozed. title: Snooze Until queued_at: anyOf: - type: string - type: 'null' description: When the current seat was claimed (queued rows) title: Queued At seat_expires_at: anyOf: - type: string - type: 'null' description: When the claimed seat is released again (queued rows). title: Seat Expires At preferred_professional_id: anyOf: - type: integer - type: 'null' description: Professional the client would rather wait for. title: Preferred Professional Id preferred_professional_name: anyOf: - type: string - type: 'null' description: Name of that professional. title: Preferred Professional Name earliest_date: anyOf: - type: string - type: 'null' description: Earliest acceptable date, `YYYY-MM-DD`. title: Earliest Date latest_date: anyOf: - type: string - type: 'null' description: Latest acceptable date, `YYYY-MM-DD`. title: Latest Date preferred_time_windows: description: 'Preferred times of day: `morning`, `afternoon`, `evening`.' items: type: string title: Preferred Time Windows type: array notes: default: '' description: Free-text notes on the entry. title: Notes type: string source: description: Where the entry came from, e.g. `api`. title: Source type: string created_at: description: Creation instant, ISO 8601 UTC. title: Created At type: string days_waiting: default: 0 description: Whole days since the entry was created. title: Days Waiting type: integer resolved_at: anyOf: - type: string - type: 'null' description: When the entry left the list, if resolved. title: Resolved At resolution_reason: anyOf: - type: string - type: 'null' description: Why it was resolved, e.g. `removed_by_user`. title: Resolution Reason created: anyOf: - type: boolean - type: 'null' description: >- On POST only: true when this call created the entry, false when an open entry already existed and its preferences were updated title: Created required: - id - waitlist_id - client - service - status - priority - source - created_at title: PublicWaitlistEntrySchema type: object PublicWaitlistClientSchema: description: The contact on a waiting-list entry. properties: id: description: Client ID. title: Id type: integer first_name: anyOf: - type: string - type: 'null' description: Given name. title: First Name last_name: anyOf: - type: string - type: 'null' description: Family name. title: Last Name phone: anyOf: - type: string - type: 'null' description: Null for email-only contacts title: Phone email: anyOf: - type: string - type: 'null' description: Email address, when known. title: Email required: - id title: PublicWaitlistClientSchema type: object PublicWaitlistServiceSchema: description: The service a waiting-list entry is for. properties: id: description: Service ID. title: Id type: integer name: description: Service name. title: Name type: string required: - id - name title: PublicWaitlistServiceSchema type: object securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: pk_... description: >- API key created in the dashboard under **Settings → API Keys**. Send it as `Authorization: Bearer pk_...`. ````