> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Book an appointment

> Books only when the business's booking_mode is instant. Returns 409 booking_requires_confirmation in request mode and 409 booking_disabled when booking is off.



## OpenAPI

````yaml /api-reference/openapi.json post /appointments
openapi: 3.1.0
info:
  title: LobbyStack API
  version: v1
  description: >-
    Read calls, contacts, appointments and messages, book appointments, and
    subscribe to webhooks. Authenticate with an API key in the Authorization
    header. Each key allows 120 requests per minute by default.
servers:
  - url: https://app.lobbystack.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Business
  - name: Calls
  - name: Contacts
  - name: Appointments
  - name: Messages
  - name: Knowledge
  - name: Webhooks
paths:
  /appointments:
    post:
      tags:
        - Appointments
      summary: Book an appointment
      description: >-
        Books only when the business's booking_mode is instant. Returns 409
        booking_requires_confirmation in request mode and 409 booking_disabled
        when booking is off.
      operationId: createAppointment
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            A unique value, up to 255 characters, that makes retries of this
            request safe for 24 hours.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Appointment'
        '400':
          description: The request is invalid (invalid_request).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid, or revoked (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks the appointments:write scope (insufficient_scope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The request conflicts with the current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests (rate_limited). Wait for the Retry-After header's
            number of seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
      security:
        - bearerAuth: []
components:
  schemas:
    AppointmentCreate:
      type: object
      properties:
        service_id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        starts_at:
          description: Start time. Use a starts_at value from GET /availability.
          type: string
          format: date-time
        contact_id:
          description: >-
            An existing contact with a phone number. Provide contact_id or
            contact_phone.
          type: string
          format: uuid
        contact_phone:
          description: Phone number in E.164 format.
          type: string
          pattern: ^\+[1-9]\d{6,14}$
        contact_name:
          type: string
          minLength: 1
          maxLength: 200
        staff_id:
          description: >-
            Book with this active staff member. Without it, LobbyStack picks one
            who is free.
          type: string
          format: uuid
        sms_consent:
          description: >-
            True only if the customer agreed to receive confirmation and
            reminder texts.
          type: boolean
      required:
        - service_id
        - starts_at
      additionalProperties: false
    Appointment:
      type: object
      properties:
        id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        status:
          type: string
          enum:
            - confirmed
            - cancelled
        starts_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
        ends_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
        timezone:
          type: string
        service_id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        service_name:
          type: string
        staff_id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        staff_name:
          type: string
        contact_id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        contact_name:
          anyOf:
            - type: string
            - type: 'null'
        contact_phone:
          anyOf:
            - type: string
            - type: 'null'
        source:
          description: >-
            Where the booking came from, for example voice, web_chat, dashboard
            or api.
          type: string
        calendar_sync_status:
          type: string
          enum:
            - pending
            - synced
            - failed
            - not_required
        created_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
        updated_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
      required:
        - id
        - status
        - starts_at
        - ends_at
        - timezone
        - service_id
        - service_name
        - staff_id
        - staff_name
        - contact_id
        - contact_name
        - contact_phone
        - source
        - calendar_sync_status
        - created_at
        - updated_at
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - unauthorized
                - forbidden
                - insufficient_scope
                - not_found
                - conflict
                - idempotency_key_reused
                - idempotency_request_in_progress
                - booking_disabled
                - booking_requires_confirmation
                - slot_unavailable
                - rate_limited
                - rate_limit_unavailable
                - method_not_allowed
                - internal_error
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from Settings > API keys. Scopes: business:read,
        business:write, calls:read, contacts:read, contacts:write,
        appointments:read, appointments:write, messages:read, knowledge:write,
        webhooks:manage.

````