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

# List Contact Reservations

> Returns reservations associated with a single contact via the contact's reservation allocations, including normalized Airbnb payout amounts when available.



## OpenAPI

````yaml GET /v1/contacts/{id}/reservations
openapi: 3.0.0
info:
  title: Conduit API
  version: 1.0.0
  description: Public API for Conduit.
servers:
  - url: https://api.conduit.ai
    description: Production
security: []
tags:
  - name: meta
    description: Discovery and API metadata endpoints.
  - name: agents
    description: >-
      V2 chat agent configuration, including instructions, skills, triggers, and
      automation behavior.
  - name: contacts
    description: >-
      Contact profile and contact-scoped related resources such as tickets and
      calls.
  - name: workspaces
    description: Workspaces accessible to the current API token.
  - name: escalations
    description: >-
      Chat escalations that require operator review, including message, proposed
      response, and disposition context when available.
  - name: conversations
    description: >-
      Canonical message threads. Use these endpoints to list threads, inspect
      conversation state, read transcripts, and send replies.
  - name: conversation-tags
    description: >-
      Conversation labels, root topics, and subtopics used for classification
      and topic analytics.
  - name: tickets
    description: >-
      Operational queue items tied to conversations, including ticket-scoped
      transcripts and replies.
  - name: calls
    description: Phone call records, transcripts, summaries, and recordings when available.
  - name: reservations
    description: >-
      PMS reservations synced from the workspace's integrations (Hostaway,
      Guesty, Airbnb, etc.), including guest identity, payment status, and stay
      dates.
  - name: appointments
    description: >-
      Scheduled appointments (bookings) backed by the Conduit booking service.
      Exposes allocation context and the upstream booking-service `external_id`.
  - name: helpdesk_tickets
    description: >-
      Helpdesk tickets mirrored from external helpdesk integrations (Zendesk,
      Pylon, Plain), including requester identity and upstream metadata.
  - name: kb
    description: >-
      Knowledge base search and node management. Nodes represent knowledge base
      entries (files or directories), chunks are the indexed retrieval units
      used by search.
  - name: skills
    description: >-
      Workspace agent skills that can be attached to V2 chat agents.
      Sidebar/global-assistant skills are intentionally excluded.
  - name: custom_tools
    description: >-
      Custom code tools: user-authored Python/JavaScript functions executed in a
      sandbox when an agent calls them. Includes a runtimes endpoint describing
      the entrypoint signature, return shape, and available dependencies per
      language.
  - name: inbox_types
    description: >-
      Workspace inbox types. Each id is stable and usable as a message trigger's
      `inboxTypeId` and as the `inbox_type_id` filter on list conversations.
  - name: workflows
    description: >-
      Workspace automation workflows: definitions, executions, and per-execution
      event timelines.
  - name: insights
    description: Aggregated workspace analytics, such as conversation automation rate.
paths:
  /v1/contacts/{id}/reservations:
    get:
      tags:
        - reservations
      summary: List reservations for a contact
      description: >-
        Returns reservations associated with a single contact via the contact's
        reservation allocations. Airbnb reservations include `airbnb_payment`
        when normalized Airbnb payout, fee, and tax amounts are available. Use
        `sort_by` to order by `arrival` (default), `departure`, or `created`.
        `order` defaults to `desc`.
      operationId: listContactReservations
      parameters:
        - schema:
            type: string
            description: Contact id.
            example: ph77c0dy0mgdpzmqz6tesry8w184002s
          required: true
          name: id
          in: path
        - schema:
            type: string
            description: >-
              Optional workspace override. If omitted, Conduit resolves the
              contact's workspace automatically.
            example: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
          required: false
          name: workspace_id
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            description: Page size. Defaults to 20. Max 100.
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: Sort direction. Defaults to `desc`.
          required: false
          name: order
          in: query
        - schema:
            type: string
            enum:
              - arrival
              - departure
              - created
            description: >-
              Primary sort field. `arrival` sorts by check-in date, `departure`
              by check-out date, `created` by booking creation time. Defaults to
              `arrival`.
          required: false
          name: sort_by
          in: query
        - schema:
            type: string
            description: >-
              Filter by reservation status. Values are PMS-normalized and vary
              by integration (common examples: `confirmed`, `cancelled`,
              `inquiry`, `new`).
            example: confirmed
          required: false
          name: status
          in: query
      responses:
        '200':
          description: Contact reservations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspace_id:
                          type: string
                        contact_id:
                          type: string
                          nullable: true
                        listing_id:
                          type: string
                          nullable: true
                        pms_platform:
                          type: string
                        external_id:
                          type: string
                        channel_name:
                          type: string
                          nullable: true
                        channel_reservation_id:
                          type: string
                          nullable: true
                        confirmation_code:
                          type: string
                          nullable: true
                        status:
                          type: string
                          nullable: true
                        source:
                          type: string
                          nullable: true
                        arrival_date:
                          type: string
                        arrival_at:
                          type: string
                          nullable: true
                        departure_date:
                          type: string
                        departure_at:
                          type: string
                          nullable: true
                        num_nights:
                          type: number
                          nullable: true
                        number_of_guests:
                          type: number
                          nullable: true
                        number_of_adults:
                          type: number
                          nullable: true
                        number_of_children:
                          type: number
                          nullable: true
                        number_of_infants:
                          type: number
                          nullable: true
                        number_of_pets:
                          type: number
                          nullable: true
                        guest:
                          type: object
                          properties:
                            name:
                              type: string
                              nullable: true
                            first_name:
                              type: string
                              nullable: true
                            last_name:
                              type: string
                              nullable: true
                            email:
                              type: string
                              nullable: true
                            phone:
                              type: string
                              nullable: true
                            country:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            locale:
                              type: string
                              nullable: true
                            external_account_id:
                              type: string
                              nullable: true
                          required:
                            - name
                            - first_name
                            - last_name
                            - email
                            - phone
                            - country
                            - city
                            - locale
                            - external_account_id
                        payment:
                          type: object
                          nullable: true
                          properties:
                            is_paid:
                              type: boolean
                            total_price:
                              type: number
                              description: >-
                                Total reservation price in major units (e.g.
                                dollars, euros) of `currency`, as reported by
                                the PMS. Not minor units (cents).
                            currency:
                              type: string
                              description: ISO 4217 currency code reported by the PMS.
                            outstanding_balance:
                              type: number
                              nullable: true
                              description: >-
                                Balance owed in major units of `currency`, when
                                reported. `null` if the PMS does not provide it.
                          required:
                            - is_paid
                            - total_price
                            - currency
                            - outstanding_balance
                        airbnb_payment:
                          type: object
                          nullable: true
                          properties:
                            currency:
                              type: string
                              nullable: true
                              description: >-
                                ISO 4217 currency code for the Airbnb payout
                                amounts, when reported.
                            expected_payout_amount:
                              type: number
                              nullable: true
                              description: >-
                                Airbnb expected host payout in major units of
                                the reservation currency.
                            expected_payout_amount_before_taxes:
                              type: number
                              nullable: true
                              description: >-
                                Airbnb expected host payout before taxes, in
                                major units of the reservation currency.
                            listing_base_price:
                              type: number
                              nullable: true
                            listing_cancellation_payout:
                              type: number
                              nullable: true
                            listing_cancellation_host_fee:
                              type: number
                              nullable: true
                            total_paid_amount:
                              type: number
                              nullable: true
                              description: >-
                                Total amount paid by the guest, when Airbnb
                                reports it.
                            transient_occupancy_tax_paid_amount:
                              type: number
                              nullable: true
                            airbnb_collected_tax_amount:
                              type: number
                              nullable: true
                            pass_through_tax_amount_paid_to_host:
                              type: number
                              nullable: true
                            pass_through_tax_expected_amount:
                              type: number
                              nullable: true
                            host_fee_base:
                              type: number
                              nullable: true
                            host_fee_vat:
                              type: number
                              nullable: true
                            guest_fee_base:
                              type: number
                              nullable: true
                            guest_fee_vat:
                              type: number
                              nullable: true
                            tax_withholding_amount:
                              type: number
                              nullable: true
                          required:
                            - currency
                            - expected_payout_amount
                            - expected_payout_amount_before_taxes
                            - listing_base_price
                            - listing_cancellation_payout
                            - listing_cancellation_host_fee
                            - total_paid_amount
                            - transient_occupancy_tax_paid_amount
                            - airbnb_collected_tax_amount
                            - pass_through_tax_amount_paid_to_host
                            - pass_through_tax_expected_amount
                            - host_fee_base
                            - host_fee_vat
                            - guest_fee_base
                            - guest_fee_vat
                            - tax_withholding_amount
                          description: >-
                            Airbnb-specific normalized payout, fee, and tax
                            amounts. `null` for non-Airbnb reservations or when
                            Airbnb did not provide payout amounts.
                        door_code:
                          type: string
                          nullable: true
                        key_code:
                          type: string
                          nullable: true
                        guest_note:
                          type: string
                          nullable: true
                        ai_paused:
                          type: boolean
                          nullable: true
                        created_at:
                          type: string
                        updated_at:
                          type: string
                          nullable: true
                      required:
                        - id
                        - workspace_id
                        - contact_id
                        - listing_id
                        - pms_platform
                        - external_id
                        - channel_name
                        - channel_reservation_id
                        - confirmation_code
                        - status
                        - source
                        - arrival_date
                        - arrival_at
                        - departure_date
                        - departure_at
                        - num_nights
                        - number_of_guests
                        - number_of_adults
                        - number_of_children
                        - number_of_infants
                        - number_of_pets
                        - guest
                        - payment
                        - airbnb_payment
                        - door_code
                        - key_code
                        - guest_note
                        - ai_paused
                        - created_at
                        - updated_at
                      description: >-
                        A reservation synced from the workspace's PMS
                        integration. `id` is the Conduit-stable identifier;
                        `external_id` is the PMS's own reservation id.
                  next_cursor:
                    type: string
                    nullable: true
                  has_more:
                    type: boolean
                required:
                  - data
                  - next_cursor
                  - has_more
                description: Cursor-paginated reservations response.
                example:
                  data:
                    - id: rs77c0dy0mgdpzmqz6tesry8w184002s
                      workspace_id: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
                      contact_id: ph77c0dy0mgdpzmqz6tesry8w184002s
                      listing_id: listing-demo-12345
                      pms_platform: Guesty
                      external_id: guesty-demo-res-001
                      channel_name: Airbnb
                      channel_reservation_id: HMDEMO1234
                      confirmation_code: HMDEMO1234
                      status: confirmed
                      source: airbnb
                      arrival_date: '2026-05-01'
                      arrival_at: '2026-05-01T15:00:00.000Z'
                      departure_date: '2026-05-05'
                      departure_at: '2026-05-05T11:00:00.000Z'
                      num_nights: 4
                      number_of_guests: 2
                      number_of_adults: 2
                      number_of_children: 0
                      number_of_infants: 0
                      number_of_pets: 0
                      guest:
                        name: Jordan Guest
                        first_name: Jordan
                        last_name: Guest
                        email: jordan.guest@example.com
                        phone: '+14155550123'
                        country: US
                        city: San Francisco
                        locale: en
                        external_account_id: airbnb_user_demo_001
                      payment:
                        is_paid: true
                        total_price: 920.5
                        currency: USD
                        outstanding_balance: 0
                      airbnb_payment:
                        currency: USD
                        expected_payout_amount: 782.4
                        expected_payout_amount_before_taxes: 735.25
                        listing_base_price: 860
                        listing_cancellation_payout: null
                        listing_cancellation_host_fee: null
                        total_paid_amount: 940.5
                        transient_occupancy_tax_paid_amount: 58.1
                        airbnb_collected_tax_amount: 42
                        pass_through_tax_amount_paid_to_host: 16.1
                        pass_through_tax_expected_amount: 16.1
                        host_fee_base: 25.8
                        host_fee_vat: 0
                        guest_fee_base: 72
                        guest_fee_vat: 0
                        tax_withholding_amount: null
                      door_code: null
                      key_code: null
                      guest_note: null
                      ai_paused: false
                      created_at: '2026-04-18T17:20:00.000Z'
                      updated_at: '2026-04-18T17:20:00.000Z'
                  next_cursor: page-token
                  has_more: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: >-
        Conduit API token. Use `Authorization: Bearer <token>`. Read/write
        endpoints require a token with write access.

````