---
title: "Creates a booking for one or more reservations."
method: POST
path: "/booking/v0-nsfw/bookings"
tags: ["Booking"]
---

# Creates a booking for one or more reservations.

`POST /booking/v0-nsfw/bookings`

## Request

- Base URL: `https://api.apaleo.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.apaleo.com/booking/v0-nsfw/bookings`
- Auth: OAuth 2
  - Implicit: `https://identity.apaleo.com/connect/authorize`
  - Scopes: `reservations.create`, `reservations.manage`, `admin`

Creates a booking taking a list of reservations as input<br>You must have at least one of these scopes: 'reservations.create, reservations.manage'.<br>For fine-grained clients, you must have this permission: 'core.bookings.create'.

## Headers

- `Idempotency-Key` string

## Request body

- CreateBookingModel: With this request you can create a booking
  - `paymentAccount` CreatePaymentAccountModel
    - `accountNumber` string, nullable: The account number (e.g. masked credit card number or last 4 digits)
    - `accountHolder` string, nullable: The account holder (e.g. card holder)
    - `expiryMonth` string, nullable: The credit card's expiration month
    - `expiryYear` string, nullable: The credit card's expiration year
    - `paymentMethod` string, nullable: The payment method (e.g. visa)
    - `payerEmail` string, nullable: The email address of the shopper / customer
    - `payerReference` string, nullable: The reference used to uniquely identify the shopper (e.g. user ID or account ID). Used for recurring payments This will become a mandatory field in the future, then it will not be possible to create an inactive payment account. Use RegisteredCard instead to add a not yet active payment account.
    - `storedPaymentMethodId` string, nullable: Optional reference to uniquely identify the stored recurring authorization, omission means the latest stored payment method for the given payerReference will be used. This is relevant when the payer has multiple stored payment methods and you want to specify which one to use for the recurring payment.
    - `isVirtual` boolean: Indicates if the payment account is a virtual credit card. If not specified it defaults to 'false'
    - `inactiveReason` string, nullable: A reason why account is inactive when PayerReference was not provided - <b>DEPRECATED: InactiveReason is deprecated. To add a payment account that is not yet active, use a RegisteredCard instead</b>
  - `registeredCard` RegisteredCardModel: Use registered card when you need to show details about a card you intend to add to the booking/reservation in the future as a real payment account. It is NOT a replacement of the deprecated PaymentAccount field.
    - `cardNumber` string, nullable: The last 4 characters of the card number
    - `cardHolder` string, nullable: The account holder (e.g. cardholder)
    - `expiryMonth` string, nullable: The credit card's expiration month
    - `expiryYear` string, nullable: The credit card's expiration year
    - `paymentMethod` string, nullable: The payment method (e.g. Visa)
    - `payerEmail` string, nullable: The email address of the shopper / customer
    - `note` string, nullable: Optional information, e.g. about card activation or failure to do so
    - `isVirtual` boolean: Indicates if the payment account is a virtual credit card.
  - `booker` BookerModel, required
    - `title` 'Mr' | 'Ms' | 'Dr' | 'Prof' | 'Mrs' | 'Other', nullable: Title of the booker
    - `gender` 'Female' | 'Male' | 'Other' | 'Unknown', nullable: Gender of the booker
    - `firstName` string, nullable: First name of the booker
    - `middleInitial` string, nullable: Middle initial of the booker
    - `lastName` string, required: Last name of the booker
    - `email` string, nullable: Email address of the booker
    - `phone` string, nullable: Phone number of the booker
    - `address` PersonAddressModel
      - `addressLine1` string, nullable
      - `addressLine2` string, nullable
      - `postalCode` string, nullable
      - `city` string, nullable
      - `regionCode` string, nullable: ISO 3166-2 region code including the country prefix (e.g. US-CA, DE-BY).
      - `countryCode` string, nullable
    - `nationalityCountryCode` string, nullable: The booker's nationality, in ISO 3166-1 alpha-2 code
    - `identificationNumber` string, nullable: The booker's identification number for the given identificationType.
    - `identificationIssueDate` string, date, nullable: The issue date of the booker's identification document.
    - `identificationExpiryDate` string, date, nullable: The expiry date of the booker's identification document.
    - `identificationType` 'SocialInsuranceNumber' | 'PassportNumber' | 'IdNumber' | 'DriverLicenseNumber' | 'VisaNumber' | 'ForeignerIdentityNumber' | 'TaxIdentificationNumber' | 'Other', nullable: The type of the identificationNumber
    - `company` PersonCompanyModel
      - `name` string, nullable: Name of the company
      - `taxId` string, nullable: Tax or Vat ID of the company
    - `preferredLanguage` string, nullable: ISO 639-1 language code (the language, not the country code): e.g. vi not vn, ja not jp, cs not cz, zh not cn.
    - `birthDate` string, date, nullable: Birth date
    - `birthPlace` string, nullable: The place of birth
  - `comment` string, nullable: Additional information and comments
  - `bookerComment` string, nullable: Additional information and comments by the booker
  - `reservations` CreateReservationModel[], required: List of reservations to create
    - `arrival` string, required: Date and optional time of arrival<br />Specify either a pure date or a date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
    - `departure` string, required: Date and optional time of departure. Cannot be more than 5 years after arrival.<br />Specify either a pure date or a date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
    - `adults` integer, required: Number of adults
    - `childrenAges` integer[], nullable: Ages of the children
    - `comment` string, nullable: Additional information and comments
    - `guestComment` string, nullable: Additional information and comments by the guest
    - `externalCode` string, nullable: Code in some system
    - `channelCode` 'Direct' | 'BookingCom' | 'Ibe' | 'ChannelManager' | 'Expedia' | 'Homelike' | 'Hrs' | 'AltoVita' | 'DesVu' | 'Gimsi', required: Channel code
    - `source` string, nullable: Source of the reservation
    - `primaryGuest` GuestModel: Guest on v0-nsfw booking endpoints. Sibling of Apaleo.Api.Modules.Booking.Models.Reservation.GuestModel (not a subclass): Swagger schema ids strip "Unstable", so inheriting the stable type would collide on "GuestModel".
      - `title` 'Mr' | 'Ms' | 'Dr' | 'Prof' | 'Mrs' | 'Other', nullable: Title of the guest
      - `gender` 'Female' | 'Male' | 'Other' | 'Unknown', nullable: Gender of the guest Allowed values for this field depend on the country in which the property is located. Use /booking/v0-nsfw/types/Gender/allowed-values to check what values are allowed.
      - `firstName` string, nullable: First name of the guest
      - `middleInitial` string, nullable: Middle initial of the guest
      - `lastName` string, required: Last name of the guest
      - `secondLastName` string, nullable: Second last name of the guest
      - `email` string, nullable: Email address of the guest
      - `phone` string, nullable: Phone number of the guest
      - `address` PersonAddressModel
        - `addressLine1` string, nullable
        - `addressLine2` string, nullable
        - `postalCode` string, nullable
        - `city` string, nullable
        - `regionCode` string, nullable: ISO 3166-2 region code including the country prefix (e.g. US-CA, DE-BY).
        - `countryCode` string, nullable
      - `nationalityCountryCode` string, nullable: The guest's nationality, in ISO 3166-1 alpha-2 code
      - `identificationNumber` string, nullable: The guest's identification number for the given identificationType.
      - `identificationAdditionalNumber` string, nullable: The guest's additional identification number for the given identificationType.
      - `identificationIssueDate` string, date, nullable: The issue date of the guest's identification document.
      - `identificationExpiryDate` string, date, nullable: The expiry date of the guest's identification document.
      - `identificationIssuePlace` string, nullable: The issue place of the guest's identification document.
      - `identificationType` 'SocialInsuranceNumber' | 'PassportNumber' | 'IdNumber' | 'DriverLicenseNumber' | 'VisaNumber' | 'ForeignerIdentityNumber' | 'TaxIdentificationNumber' | 'Other', nullable: The type of the identificationNumber Allowed values for this field depend on the country in which the property is located. Use /booking/v0-nsfw/types/IdentificationType/allowed-values to check what values are allowed.
      - `personalTaxId` string, nullable: The personal tax id of the guest
      - `company` PersonCompanyModel
        - `name` string, nullable: Name of the company
        - `taxId` string, nullable: Tax or Vat ID of the company
      - `preferredLanguage` string, nullable: ISO 639-1 language code (the language, not the country code): e.g. vi not vn, ja not jp, cs not cz, zh not cn.
      - `birthDate` string, date, nullable: Guest's birthdate
      - `birthPlace` string, nullable: Guest's place of birth
      - `birthFirstName` string, nullable: Guest's first name right after birth
      - `birthLastName` string, nullable: Guest's last name right after birth
      - `motherFirstName` string, nullable: Guest's mother's first name
      - `motherLastName` string, nullable: Guest's mother's last name
      - `borderCrossingPlace` string, nullable: The place through which the guest crossed the border
      - `borderCrossingDate` string, date, nullable: Date on which the guest crossed the border
      - `nextDestination` string, nullable: The guest's next destination address
      - `relationshipToPrimaryGuest` 'Grandparent' | 'Grandchild' | 'GreatGrandparent' | 'GreatGrandchild' | 'Parent' | 'Child' | 'Sibling' | 'ParentInLaw' | 'ChildInLaw' | 'SiblingInLaw' | 'Spouse' | 'UncleOrAunt' | 'NephewOrNiece' | 'Guardian' | 'Other', nullable: The relationship of the guest to the primary guest.
      - `vehicleRegistration` VehicleRegistrationModel
        - `number` string, nullable: The number of a vehicle registration plate
        - `countryCode` string, nullable: Code of the country of vehicle registration
      - `loyaltyMemberships` LoyaltyMembershipModel[], nullable: Loyalty program memberships of the guest. Stored as sent; program codes are not validated against a catalog.
        - `program` string, nullable: Loyalty program code. Stored as sent; not validated against a catalog.
        - `membershipNumber` string, nullable: Membership number in the loyalty program.
        - `tier` string, nullable: Optional loyalty tier. Stored as sent.
      - `isVip` boolean, nullable: Whether the guest is a VIP. Omitted on update leaves the stored value unchanged. Omitted on create means the guest is not a VIP.
      - `marketingConsent` MarketingConsentModel
        - `granted` boolean, required: Whether the guest granted marketing consent.
        - `capturedAt` string, date-time, nullable: When the guest gave or withdrew consent. Defaults to the time Apaleo receives the write.<br />A date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
        - `source` string, nullable: Free-text source of the consent, e.g. booking-engine, front-desk, comms-app.
        - `receivedAt` string, date-time, nullable: Set by Apaleo whenever a write changes the consent. Ignored on input.<br />A date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
    - `additionalGuests` GuestModel[], nullable: Additional guests of the reservation.
      - `title` 'Mr' | 'Ms' | 'Dr' | 'Prof' | 'Mrs' | 'Other', nullable: Title of the guest
      - `gender` 'Female' | 'Male' | 'Other' | 'Unknown', nullable: Gender of the guest Allowed values for this field depend on the country in which the property is located. Use /booking/v0-nsfw/types/Gender/allowed-values to check what values are allowed.
      - `firstName` string, nullable: First name of the guest
      - `middleInitial` string, nullable: Middle initial of the guest
      - `lastName` string, required: Last name of the guest
      - `secondLastName` string, nullable: Second last name of the guest
      - `email` string, nullable: Email address of the guest
      - `phone` string, nullable: Phone number of the guest
      - `address` PersonAddressModel
        - `addressLine1` string, nullable
        - `addressLine2` string, nullable
        - `postalCode` string, nullable
        - `city` string, nullable
        - `regionCode` string, nullable: ISO 3166-2 region code including the country prefix (e.g. US-CA, DE-BY).
        - `countryCode` string, nullable
      - `nationalityCountryCode` string, nullable: The guest's nationality, in ISO 3166-1 alpha-2 code
      - `identificationNumber` string, nullable: The guest's identification number for the given identificationType.
      - `identificationAdditionalNumber` string, nullable: The guest's additional identification number for the given identificationType.
      - `identificationIssueDate` string, date, nullable: The issue date of the guest's identification document.
      - `identificationExpiryDate` string, date, nullable: The expiry date of the guest's identification document.
      - `identificationIssuePlace` string, nullable: The issue place of the guest's identification document.
      - `identificationType` 'SocialInsuranceNumber' | 'PassportNumber' | 'IdNumber' | 'DriverLicenseNumber' | 'VisaNumber' | 'ForeignerIdentityNumber' | 'TaxIdentificationNumber' | 'Other', nullable: The type of the identificationNumber Allowed values for this field depend on the country in which the property is located. Use /booking/v0-nsfw/types/IdentificationType/allowed-values to check what values are allowed.
      - `personalTaxId` string, nullable: The personal tax id of the guest
      - `company` PersonCompanyModel
        - `name` string, nullable: Name of the company
        - `taxId` string, nullable: Tax or Vat ID of the company
      - `preferredLanguage` string, nullable: ISO 639-1 language code (the language, not the country code): e.g. vi not vn, ja not jp, cs not cz, zh not cn.
      - `birthDate` string, date, nullable: Guest's birthdate
      - `birthPlace` string, nullable: Guest's place of birth
      - `birthFirstName` string, nullable: Guest's first name right after birth
      - `birthLastName` string, nullable: Guest's last name right after birth
      - `motherFirstName` string, nullable: Guest's mother's first name
      - `motherLastName` string, nullable: Guest's mother's last name
      - `borderCrossingPlace` string, nullable: The place through which the guest crossed the border
      - `borderCrossingDate` string, date, nullable: Date on which the guest crossed the border
      - `nextDestination` string, nullable: The guest's next destination address
      - `relationshipToPrimaryGuest` 'Grandparent' | 'Grandchild' | 'GreatGrandparent' | 'GreatGrandchild' | 'Parent' | 'Child' | 'Sibling' | 'ParentInLaw' | 'ChildInLaw' | 'SiblingInLaw' | 'Spouse' | 'UncleOrAunt' | 'NephewOrNiece' | 'Guardian' | 'Other', nullable: The relationship of the guest to the primary guest.
      - `vehicleRegistration` VehicleRegistrationModel
        - `number` string, nullable: The number of a vehicle registration plate
        - `countryCode` string, nullable: Code of the country of vehicle registration
      - `loyaltyMemberships` LoyaltyMembershipModel[], nullable: Loyalty program memberships of the guest. Stored as sent; program codes are not validated against a catalog.
        - `program` string, nullable: Loyalty program code. Stored as sent; not validated against a catalog.
        - `membershipNumber` string, nullable: Membership number in the loyalty program.
        - `tier` string, nullable: Optional loyalty tier. Stored as sent.
      - `isVip` boolean, nullable: Whether the guest is a VIP. Omitted on update leaves the stored value unchanged. Omitted on create means the guest is not a VIP.
      - `marketingConsent` MarketingConsentModel
        - `granted` boolean, required: Whether the guest granted marketing consent.
        - `capturedAt` string, date-time, nullable: When the guest gave or withdrew consent. Defaults to the time Apaleo receives the write.<br />A date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
        - `source` string, nullable: Free-text source of the consent, e.g. booking-engine, front-desk, comms-app.
        - `receivedAt` string, date-time, nullable: Set by Apaleo whenever a write changes the consent. Ignored on input.<br />A date and time in UTC or with UTC offset as defined in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO8601:2004</a>
    - `guaranteeType` 'PM6Hold' | 'CreditCard' | 'Prepayment' | 'Company', nullable: The guarantee that has to be applied for this reservation. It has to be the same or stronger than the minimum guarantee required by the selected rate plan
    - `travelPurpose` 'Business' | 'Leisure', nullable: Purpose of the trip, leisure or business
    - `timeSlices` CreateReservationTimeSliceModel[], required: Gross prices including services and taxes for each time slice. They will be applied to the reservation timeslices in the order specified from arrival to departure
      - `ratePlanId` string, required: The rate plan id for this time slice
      - `totalAmount` MonetaryValueModel
        - `amount` number, double, required
        - `currency` string, required
    - `services` BookReservationServiceModel[], nullable: Additional services (extras, add-ons) that should be added to the reservation
      - `serviceId` string, required: The id of the service you want to book
      - `count` integer, nullable: The number of services to book for each service date. It defaults to the service offer count when not specified.
      - `amount` MonetaryValueModel
        - `amount` number, double, required
        - `currency` string, required
      - `dates` Date[], nullable: The optional dates you want to book the service for; if not specified the default service pattern will be used (e.g. whole stay).
        - `serviceDate` string, date, required: The date the service is delivered
        - `count` integer, nullable: The number of services to book for this date. It defaults to the service offer count when not specified.
        - `amount` MonetaryValueModel
          - `amount` number, double, required
          - `currency` string, required
    - `companyId` string, nullable: Set this if this reservation belongs to a company
    - `corporateCode` string, nullable: Corporate code provided during creation. Used to find offers during amend.
    - `prePaymentAmount` MonetaryValueModel
      - `amount` number, double, required
      - `currency` string, required
    - `commission` CommissionModel
      - `commissionAmount` MonetaryValueModel, required
        - `amount` number, double, required
        - `currency` string, required
      - `beforeCommissionAmount` MonetaryValueModel
        - `amount` number, double, required
        - `currency` string, required
    - `promoCode` string, nullable: The promo code associated with a certain special offer
    - `externalReferences` CreateExternalReferencesModel
      - `globalDistributionSystemId` string, nullable: The ID of the global distribution system.
      - `onlineTravelAgencyId` string, nullable: The ID of the online travel agency.
      - `onlineBookingToolId` string, nullable: The ID of the online booking tool.
      - `channelManagerId` string, nullable: The ID of the channel manager.
      - `centralReservationSystemId` string, nullable: The ID of the central reservation system.
    - `registeredCard` RegisteredCardModel: Use registered card when you need to show details about a card you intend to add to the booking/reservation in the future as a real payment account. It is NOT a replacement of the deprecated PaymentAccount field.
      - `cardNumber` string, nullable: The last 4 characters of the card number
      - `cardHolder` string, nullable: The account holder (e.g. cardholder)
      - `expiryMonth` string, nullable: The credit card's expiration month
      - `expiryYear` string, nullable: The credit card's expiration year
      - `paymentMethod` string, nullable: The payment method (e.g. Visa)
      - `payerEmail` string, nullable: The email address of the shopper / customer
      - `note` string, nullable: Optional information, e.g. about card activation or failure to do so
      - `isVirtual` boolean: Indicates if the payment account is a virtual credit card.
  - `transactionReference` string, nullable: The reference of a payment transaction. This should be set when a payment transaction has been initiated and should be used to complete the transaction upon reservation creation. When set, the payment transaction completion is always triggered regardless of the reservation guarantee type and payment automation settings.

## Response `201`

All new reservations were created.

- BookingCreatedModel
  - `id` string, required: Booking id
  - `reservationIds` ReservationCreatedModel[], required: List of ids for newly created reservations
    - `id` string, required: Id of the reservation

## Other responses

- `400`: Bad request.
- `401`: You are unauthorized.
- `403`: Forbidden.
- `404`: The Request-URI could not be found.
- `415`: Unsupported media type.
- `422`: Validation errors in the request body or query params.
- `499`: Client closed request.
- `500`: An unexpected error occurred.
- `503`: The server is currently unavailable. Please try later.

---

[API](https://skmtc.dev/apaleo/apis/apaleo-booking-api-not-safe-for-work.md) - [All operations](https://skmtc.dev/apaleo/apis/apaleo-booking-api-not-safe-for-work/llms.txt) - [OpenAPI document](https://skmtc.dev/apaleo/apis/apaleo-booking-api-not-safe-for-work/revisions/a1b6a2f6b879?raw)