Despegar Booking API

openapi: 3.0.3
info:
  title: Activities Availability Booking API
  version: 1.0.0
  description: 'API for activities: tickets, modalities, availability, prebook, payments, and booking. Authentication via API Key.'
servers:
- url: https://api-dev.despegar.com/v3/activities-api
  description: Sandbox
- url: https://apis-uat.despegar.com/v3/activities-api
  description: UAT
- url: https://api.despegar.com/v3/activities-api
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Booking
paths:
  /book:
    post:
      tags:
      - Booking
      summary: Book
      operationId: createBooking
      parameters:
      - in: query
        name: test_case
        schema:
          type: string
          enum:
          - pricejump
        description: Optional parameter for testing purposes. Use 'pricejump' to simulate a price jump scenario.
        required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prebook_id
              - external_booking_reference
              - modality
              - contact_data
              - travelers
              - payment
              properties:
                prebook_id:
                  type: string
                  description: ID obtained from the prebook response.
                external_booking_reference:
                  type: string
                  description: External booking reference.
                modality:
                  type: string
                  enum:
                  - PAYINADVANCE
                  description: Payment modality.
                contact_data:
                  type: object
                  description: Buyer contact information.
                  required:
                  - email
                  - phones
                  properties:
                    email:
                      type: string
                      description: Buyer's email address.
                    phones:
                      type: array
                      description: List of contact phone numbers.
                      items:
                        required:
                        - country_code
                        - area_code
                        - number
                        - type
                        properties:
                          country_code:
                            type: string
                            description: 'Phone country code. E.g.: ''55''.'
                          area_code:
                            type: string
                            description: 'Phone area code. E.g.: ''11''.'
                          number:
                            type: string
                            description: Phone number.
                          type:
                            type: string
                            enum:
                            - HOME
                            - MOBILE
                            description: Phone type.
                travelers:
                  type: array
                  description: List of travelers.
                  items:
                    required:
                    - first_name
                    - last_name
                    properties:
                      first_name:
                        type: string
                        description: 'Traveler''s first name. Required for: FLIGHT, HOTEL, TICKET.'
                      last_name:
                        type: string
                        description: 'Traveler''s last name. Required for: FLIGHT, HOTEL, TICKET.'
                      gender:
                        type: string
                        enum:
                        - MALE
                        - FEMALE
                        description: Traveler's gender.
                      nationality:
                        type: string
                        description: 'Traveler''s nationality as ISO country code. E.g.: ''br'', ''mx''.'
                      birth_date:
                        type: string
                        description: 'Traveler''s date of birth. Format: YYYY-MM-DD.'
                      identification:
                        type: object
                        description: 'Traveler''s identification document. Required for: FLIGHT, TICKET.'
                        properties:
                          type:
                            type: string
                            enum:
                            - LOCAL
                            - PASSPORT
                            description: 'Traveler''s document type. Required for: FLIGHT, TICKET.'
                          number:
                            type: string
                            description: 'Traveler''s document number. Required for: FLIGHT, TICKET.'
                payment:
                  type: object
                  description: 'Payment information. The ''option_type'' field determines which sub-fields are required: CURRENT_ACCOUNT and FULL_POINTS do not include ''payment_units''; ONE_CARD and DEFERRED do.'
                  required:
                  - option_type
                  properties:
                    option_type:
                      type: string
                      enum:
                      - CURRENT_ACCOUNT
                      - ONE_CARD
                      - DEFERRED
                      description: Payment method type.
                    payment_units:
                      type: array
                      description: Only sent with option_type ONE_CARD or DEFERRED.
                      items:
                        properties:
                          type:
                            type: string
                            enum:
                            - ONE_CARD
                            - CURRENT_ACCOUNT
                            - DEFERRED
                            description: Payment unit type. Use CARD for ONE_CARD, DEFERRED for DEFERRED.
                          invoice_reference:
                            type: number
                            description: 'Reference to the corresponding invoice. E.g.: 0.'
                          plan_id:
                            type: string
                            description: Payment plan ID. Only sent with option_type ONE_CARD.
                          secure_token:
                            type: string
                            description: Card secure token. Only sent with option_type ONE_CARD.
                          card_holder_identification:
                            type: object
                            description: Card holder identification. Only sent with option_type ONE_CARD.
                            properties:
                              type:
                                type: string
                                enum:
                                - LOCAL
                                - PASSPORT
                                description: Card holder document type.
                              number:
                                type: string
                                description: Card holder document number.
                    invoices:
                      type: array
                      description: Buyer fiscal data. Present in all option_type values.
                      items:
                        required:
                        - fiscal_status
                        - fiscal_identification
                        properties:
                          reference:
                            type: number
                            description: 'Invoice reference. E.g.: 0. Only sent with option_type ONE_CARD'
                          fiscal_name:
                            type: string
                            description: Full fiscal name.
                          first_name:
                            type: string
                            description: First name. Only sent with option_type CURRENT_ACCOUNT
                          last_name:
                            type: string
                            description: Last name. Only sent with option_type CURRENT_ACCOUNT
                          fiscal_status:
                            type: string
                            enum:
                            - PERSONA_FISICA
                            description: Fiscal status of the holder.
                          fiscal_identification:
                            type: object
                            required:
                            - type
                            - number
                            properties:
                              type:
                                type: string
                                enum:
                                - CPF
                                - PASSPORT
                                description: 'Fiscal document type. Required for: CURRENT_ACCOUNT (all products).'
                              number:
                                type: string
                                description: 'Fiscal document number. Required for: CURRENT_ACCOUNT (all products).'
                              issue_country:
                                type: string
                                description: Document issuing country. Only sent if fiscal_identification.type is PASSPORT.
                          fiscal_address:
                            type: object
                            properties:
                              city_id:
                                type: string
                                description: City ID.
                              zip_code:
                                type: string
                                description: Postal code.
                              street:
                                type: string
                                description: 'Street name. Required for: CURRENT_ACCOUNT (all products).'
                              number:
                                type: string
                                description: Street number.
                              neighbourhood:
                                type: string
                                description: Neighbourhood. Only sent with option_type ONE_CARD AND DEFERRED.
                              apartment:
                                type: string
                                description: Apartment.
                              floor:
                                type: string
                                description: Floor.
                loyalty_data:
                  type: object
                  description: Loyalty program data. Only sent with option_type ONE_CARD.
                  properties:
                    redemption_points:
                      type: number
                      description: Points to redeem. Send 0 when option_type is ONE_CARD.
            examples:
              ONE_CARD:
                summary: Payment with credit/debit card
                value:
                  prebook_id: prebook-id-value
                  external_booking_reference: REF-001
                  modality: PAYINADVANCE
                  contact_data:
                    email: maria.silva@example.com
                    phones:
                    - country_code: '55'
                      area_code: '11'
                      number: '912345678'
                      type: MOBILE
                  travelers:
                  - traveler_reference_id: '0'
                    first_name: Maria
                    last_name: Silva
                    gender: FEMALE
                    nationality: BR
                    birth_date: '1990-03-05'
                    identification:
                      type: PASSPORT
                      number: AB1234567
                      issue_country: BR
                  payment:
                    option_type: ONE_CARD
                    payment_units:
                    - type: ONE_CARD
                      plan_id: plan-id-value
                      secure_token: secure-token-value
                      invoice_reference: 1
                      card_holder_identification:
                        type: LOCAL
                        number: 123.456.789-09
                    invoices:
                    - reference: 1
                      fiscal_name: Maria Silva
                      first_name: Maria
                      last_name: Silva
                      fiscal_status: PERSONA_FISICA
                      fiscal_identification:
                        type: CPF
                        number: '12345678909'
                      fiscal_address:
                        street: Rua das Flores
                        number: '42'
                        city_id: '7274'
                        zip_code: 01310-100
              CURRENT_ACCOUNT:
                summary: Payment with current account
                value:
                  prebook_id: prebook-id-value
                  external_booking_reference: REF-002
                  modality: PAYINADVANCE
                  contact_data:
                    email: carlos.souza@example.com
                    phones:
                    - country_code: '55'
                      area_code: '21'
                      number: '987654321'
                      type: HOME
                  travelers:
                  - traveler_reference_id: '0'
                    first_name: Carlos
                    last_name: Souza
                    identification:
                      type: LOCAL
                      number: '12345678909'
                  payment:
                    option_type: CURRENT_ACCOUNT
                    payment_units:
                    - type: CURRENT_ACCOUNT
                    invoices:
                    - fiscal_name: Carlos Souza
                      first_name: Carlos
                      last_name: Souza
                      fiscal_status: PERSONA_FISICA
                      fiscal_identification:
                        type: CPF
                        number: '98765432100'
                      fiscal_address:
                        street: Av Paulista
                        number: '1000'
                        city_id: '7274'
                        zip_code: 01310-200
              DEFERRED:
                summary: Payment with deferred method
                value:
                  prebook_id: prebook-id-value
                  external_booking_reference: REF-003
                  modality: PAYINADVANCE
                  contact_data:
                    email: ana.lima@example.com
                    phones:
                    - country_code: '55'
                      area_code: '31'
                      number: '912398765'
                      type: MOBILE
                  travelers:
                  - traveler_reference_id: '0'
                    first_name: Ana
                    last_name: Lima
                    gender: FEMALE
                    nationality: BR
                    birth_date: '1992-11-20'
                    identification:
                      type: LOCAL
                      number: '98765432100'
                  payment:
                    option_type: DEFERRED
                    payment_units:
                    - type: DEFERRED
                      plan_id: plan-id-value
                      secure_token: secure-token-value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - title: CONFIRMED_BOOKING
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: SUCCESS
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                          pnr:
                            type: number
                - title: PROCESSING
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: PROCESSING
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                          pnr:
                            type: number
                - title: UNAVAILABLE_FLIGHT
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                    sub_status:
                      type: string
                      description: UNAVAILABLE_FLIGHT
                    message:
                      type: string
                      description: 'Booking failed with error: UNAVAILABLE_FLIGHT'
                - title: INTERNAL_ERROR
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                    sub_status:
                      type: string
                      description: INTERNAL_ERROR
                    message:
                      type: array
                      description: List of allowed/possible values for message.
                      items:
                        type: object
                        properties:
                          message1:
                            type: string
                            description: RETRIEVE_ITINERARY_FAILED. Retrieve error.
                          message2:
                            type: string
                            description: 'norris call error - status: 500 Internal Server Error'
                - title: PROVIDER_ERROR
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                    sub_status:
                      type: string
                      description: PROVIDER_ERROR
                    message:
                      type: array
                      description: List of allowed/possible values for message.
                      items:
                        type: object
                        properties:
                          message1:
                            type: string
                            description: PROVIDER_ERROR. ProviderError.
                          message2:
                            type: string
                            description: 'Booking failed with error: PROVIDER_ERROR'
                          message3:
                            type: string
                            description: PROVIDER_ERROR. The server encountered an unexpected condition which prevented it from fulfilling the request
                - title: PRICE_JUMP
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                          plataform_id:
                            type: number
                          pnr:
                            type: string
                    sub_status:
                      type: string
                      description: PRICE_JUMP
                    message:
                      type: array
                      description: List of allowed/possible values for message.
                      items:
                        type: object
                        properties:
                          message1:
                            type: string
                            description: NOT_TOLERABLE
                          message2:
                            type: string
                            description: INTERACTIVE - Not supported
                - title: DUPLICATED_RESERVATION
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: FLIGHT
                    sub_status:
                      type: string
                      description: DUPLICATED_RESERVATION
                    message:
                      type: array
                      description: List of allowed/possible values for message.
                      items:
                        type: object
                        properties:
                          message1:
                            type: string
                            description: Duplicated transaction
                - title: CHANNEL_REJECTED
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: FLIGHT
                    sub_status:
                      type: string
                      description: ChannelRejected
                    message:
                      type: string
                      description: ''
                - title: INSUFFICIENT_FUNDS
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: string
                      description: IndsufficientFunds
                    message:
                      type: string
                      description: Indsufficient funds
                - title: REFERRED
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: string
                      description: Referred
                    message:
                      type: string
                      description: A process with the card issuer is required.
                - title: UNSUPPORTED_OPERATION
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: string
                      description: UnsupportedOperation
                    message:
                      type: string
                      description: Error with the payment provider
                - title: RISK_REJECTED
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: string
                      description: RiseRejected
                    message:
                      type: string
                      description: Rejected by Risk
                - title: INVALID_CARD
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: string
                      description: InvalidCard
                - title: PUNTOS
                  type: object
                  properties:
                    reservationId:
                      type: string
                    status:
                      type: string
                      description: ERROR
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Product
                    sub_status:
                      type: array
                      description: Two diferentes status
                      items:
                        type: object
                        properties:
                          status1:
                            type: string
                            description: CONFIRM DISCOUNT
                          status2:
                            type: string
                            description: REDEMPTION CANCELLATION
                    message:
                      type: array
                      description: ' '
                      items:
                        type: object
                        properties:
                          message:
                            type: string
                            description: ''
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - title: INVALID_FIELD
                  description: 'Possible cause: The booking request contains invalid or incomplete data in one or more required fields.'
                  type: object
                  properties:
                    option1:
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                          description: A field has an invalid value.
                    option2:
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                          description: the Book request contains missing, blank, or invalid required fields.
                - title: BAD_REQUEST
                  description: 'Possible cause: Book service (including reservation query) executed without sending the ''Authorization'' header'
                  type: object
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                      description: Authorization header is missing.
                - title: INVALID_PREBOOK_ID
                  description: Book executed with invalid 'prebook_id'
                  type: object
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                      description: Invalid identifier format
                - title: MESSAGE_NOT_READABLE
                  description: 'Possible cause: The Book request was sent with blank or malformed fields across multiple sections (contact_data.phones.type, travelers.gender/birth_date/identification.type, payment.payment_units.invoice_reference, payment.invoices.reference/fiscal_status, loyalty_data.redemption_points, payment.invoices.fiscal_identification.expiration_date), causing type mismatches, unsupported enum values, and invalid date/number formats.'
                  type: object
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                      description: ' JSON parse/validation error - empty, invalid, or unsupported value; wrong type; or malformed date/number (e.g., unsupported enum, alphabetic/numeric where not allowed, incorrect date format).'
                - title: PAYMENT_ERROR
                  description: 'Possible cause: Current account without available balance'
                  type: object
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                      description: Cannot pay due to current account status.
                - title: PAYMENT_OPTION_NOT_FOUND
                  description: 'Possible cause: Book executed without sending ''modality'' or ''payment -> option_type'''
                  type: object
                  p

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/despegar/refs/heads/main/openapi/despegar-booking-api-openapi.yml