Managing contracting flow

This section describes all the possible actions related to the Booking.com contracting process using the Contracting API.

Quick actions

POST
https://supply-xml.booking.com/contracts-api/partners/invite

The POST /partners/invite request enables you to send the legal details of a new Accommodation Partner to create their legal entity id. If the request is successful, you immediately retrieve the legal entity ID in the response.

A successfull request also triggers an email to be sent to the new Accommodation Partner with a link to the Booking.com contracting tool. The Accommodation Partner must sign the contract before you can set a property as open and bookable.

Body parameters

The following table describes what elements you must add as body parameters:

Element Description Type Required/Optional Notes
legal_contact_email Specifies the Accommodation Partner's legal contact email. string required The system sees this email as the unique identifier for the Accommodation Partner.
legal_contact_name Specifies the Accommodation Partner's legal contact name. string required
legal_contact_phone_number Specifies the Accommodation Partner's legal contact phone number. string optional Follows ITU E.164.
legal_name Specifies the legal name of the Accommodation Partner company. string optional
preferred_language Specifies the preferred language in which the Accommodation Partner wants to communicate. string required For the language codes, see Booking.com Language Code
company_name Specifies the commercial name of the Accommodation Partner company. string required
website Specifies the website of the Accommodation Partner company. string optional
total_number_of_properties Specifies the amount of properties connected to the Accommodation Partner. string optional
country Specifies the country of the Accommodation Partner company. string optional To retrieve a list of the available country codes, see retrieving country codes
city Specifies the city of the Accommodation Partner company. string optional
zipcode Specifies the zipcode of the Accommodation Partner company. string optional
street Specifies the street of the Accommodation Partner company. string optional
is_test Indicates whether the legal entity ID (for an Accommodation Partner) you want to create is for testing purposes. boolean optional The default value is 0. See Creating a test partner to follow best practices.
contract_countries Contains the countries in which the Accommodation Partner has properties. array optional You should include all the countries in which the Accommodation Partner has properties in. To retrieve a list of the available country codes, see retrieving country codes

Request body example

The following is a request body example:

{
    "city": "Amsterdam",
    "company_name": "Giovanni hotels",
    "country": "nl",
    "legal_contact_email": "don.giovanni@hotel.com",
    "contract_countries": [
        "fr", "nl"
      ],
    "legal_contact_name": "Don Giovanni",
    "legal_contact_phone_number": "+1234567890",
    "legal_name": "Giovanni hotels BV",
    "preferred_language": "xu",
    "street": "Streetstreet",
    "total_number_of_properties": 2,
    "zipcode": "1000AB",
    "website": "https://www.besthotel.com",
    "is_test": 0
   }

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YeobhK72bvPcV0nJP9QOSA+dzomZn9+s+9FQ9kgxfFX4ENvHYNN0LCnFNICpW0ciFwK1qAKX8jr7j4KTc3UQb3zqaliHlsArhQ=="
    },
    "errors": [],
    "data": {
        "legal_entity_id": 425500
    },
    "warnings": []
 }

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: legal_entity_id Specifies the unique legal entity id. integer
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array
POST
https://supply-xml.booking.com/contracts-api/partners/legal-details

The POST /partners/legal-details request enables you to do the following:

  • Check whether the contract has been signed: It is recommended to poll this endpoint at least once a day for this information. If after a few days the Accommodation Partner still has not signed the contract, resend the email with link to contracting tool.
  • Verify whether the legal contact email is already known to Booking.com: This is particularly useful when you have a new Accommodation Partner that already has properties on Booking.com.
  • Retrieve the following legal details:

    • The Accommodation Partner's legal entity id.
    • The Accommodation Partner's legal details.
    • (In case the contract is signed): A list of countries in which the Accommodation Partner has properties.

Body parameters

The following table describes what elements you must add as body parameters:

Element Description Type Required/Optional Notes
legal_contact_email Specifies the Accommodation Partner's legal contact email. string required The system sees this email as the unique identifier for the Accommodation Partner.
is_test Indicates whether you want to retrieve the legal details for (0) non-test Accommodation Partners or (1) test Accommodation Partners. boolean optional If you do not add this parameter, the system returns the legal details of any Accommodation Partner associated with the given legal contact email, does not matter if it is test or non-test.

Request body example

The following is a request body example:

{
    "legal_contact_email": "don.giovanni@hotel.com"
   }

Response body example

The following is a successful response body example:

{
  "errors": [],
  "warnings": [],
  "data": {
      "legal_entity_id": 248253,
      "city": "Amsterdam",
      "company_name": "Giovanni hotels",
      "contract_countries": ["France", "Netherlands"],
      "total_number_of_properties": 2,
      "legal_contact_phone_number": "+1234567890",
      "legal_contact_name": "Don Giovanni",
      "country": "Netherlands",
      "legal_contact_email": "don.giovanni@hotel.com",
      "contract_signed": 1
  },
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YV3xmhN2gmpevUrYwxpUoN/jn9fLQqzlAeYCc/LIw2lyMwM4mn41o/dbebomYx1ySDfJDoCMIddlrB0S91gH+rcSEfwBO2Mi9tlS4lX11o5eWs5uCjhZ3qO+epbOZxN+4rgU4f"
  }
}

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: contract_countries Contains the countries for which the Accommodation Partner has signed a contract. array You can only see this array when the contract is signed.
: legal_entity_id Specifies the unique legal entity id. integer
: contract_signed Indicates whether the contract is signed. boolean
: legal_contact_name Specifies the Accommodation Partner's legal contact name. string
: legal_contact_phone_number Specifies the Accommodation Partner's legal contact phone number. string Follows the ITU E.164 standard.
: company_name Specifies the commercial name of the Accommodation Partner company. string
: total_number_of_properties Specifies the amount of properties connected to the Accommodation Partner. string
: country Specifies the country of the Accommodation Partner. string
: city Specifies the city of the Accommodation Partner. string
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array
GET
https://supply-xml.booking.com/contracts-api/partners/legal-details/legal-entity/248253

The GET /partners/legal-details/legal-entity/<id> request enables you to do the following:

  • Check whether you are connected to the Accommodation Partner on the hotel or partner level: Existing partner cards sometimes do not have complete data. For example, partner cards are not connected to a specific hotel account. In such scenarios retrieving legal details with their email does not work.
  • Retrieve the following legal details:

    • The Accommodation Partner's legal details.
    • (In case the contract is signed): A list of countries in which the Accommodation Partner has signed contract to build properties.

Response body example

The following is a successful response body example:

{
  "errors": [],
  "warnings": [],
  "data": {
      "legal_entity_id": 248253,
      "city": "Amsterdam",
      "company_name": "Giovanni hotels",
      "contract_countries": ["France", "Netherlands"],
      "total_number_of_properties": 2,
      "legal_contact_phone_number": "+1234567890",
      "legal_contact_name": "Don Giovanni",
      "country": "Netherlands",
      "legal_contact_email": "don.giovanni@hotel.com",
      "contract_signed": 1
  },
  "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9YV3xmhN2gmpevUrYwxpUoN/jn9fLQqzlAeYCc/LIw2lyMwM4mn41o/dbebomYx1ySDfJDoCMIddlrB0S91gH+rcSEfwBO2Mi9tlS4lX11o5eWs5uCjhZ3qO+epbOZxN+4rgU4f"
  }
}

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: contract_countries Contains the countries for which the Accommodation Partner has signed a contract. array You can only see this array when the contract is signed.
: legal_entity_id Specifies the unique legal entity id. integer
: contract_signed Indicates whether the contract is signed. boolean
: legal_contact_name Specifies the Accommodation Partner's legal contact name. string
: legal_contact_phone_number Specifies the Accommodation Partner's legal contact phone number. string Follows the ITU E.164 standard.
: company_name Specifies the commercial name of the Accommodation Partner company. string
: total_number_of_properties Specifies the amount of properties connected to the Accommodation Partner. string
: country Specifies the country of the Accommodation Partner. string
: city Specifies the city of the Accommodation Partner. string
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array
POST
https://supply-xml.booking.com/contracts-api/partners/resend-invite

The POST /partners/resend-invite request enables you to resend the email to the Accommodation Partner with a link to the Booking.com contracting tool.

The Accommodation Partner must sign the contract before you can set a property as open and bookable, so use this endpoint as a reminder to the Accommodation Partner.

Body parameters

The following table describes what elements you must add as body parameters:

Element Description Type Required/Optional Notes
legal_contact_email Specifies the Accommodation Partner's legal contact email. string required The system sees this email as the unique identifier for the Accommodation Partner.
is_test Indicates whether you want to resend invite to a (0) non-test Accommodation Partners or (1) test Accommodation Partners. boolean optional If you do not add this parameter, the system looks for any Accommodation Partner associated with the given legal contact email, does not matter if it is test or non-test.

Request body example

The following is a request body example:

{
    "legal_contact_email": "don.giovanni@hotel.com"
   }

Response body example

The following is a successful response body example:

{
    "data": {
        "success": 1,
        "status": "Invitation sent to Partner!"
    },
    "errors": [],
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YeobhK72wd23f3rgIGBV43CLA0/7JFJASBu0RvfbcDMZPMJ2upJzzPiWPpgrz8CqgrYuylZFVYdIxxxjTysIR2C7iIMdzNV9aw=="
    }
 }

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: success Indicates the success of the operation . boolean
: status Specifies the status of the operation. string
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Adding an additional country to an existing contract

POST
https://supply-xml.booking.com/contracts-api/partners/addendum

The POST /partners/addendum request enables you to add additional countries, in which an Accommodation Partner has properties, to an existing contract.

A successfull request also triggers an email to be sent to the Accommodation Partner with a link to the Booking.com contracting tool. The Accommodation Partner must sign the contract each time they want to onboard a property in an additional country (a country for which the contract is not signed yet).

Body parameters

The following table describes what elements you must add as body parameters:

Element Description Type Required/Optional Notes
legal_contact_email Specifies the Accommodation Partner's legal contact email. string required The system sees this email as the unique identifier for the Accommodation Partner.
additional_countries Contains the additional country or countries in which the Accommodation Partner has properties. array required
is_test Indicates whether you want to add an additional country to the existing contract of a (0) non-test Accommodation Partner or (1) a test Accommodation Partner. boolean optional

Request body example

The following is a request body example:

{
  "additional_countries": [
    "be"
  ],
  "legal_contact_email": "don.giovanni@hotel.com"
}

Response body example

The following is a successful response body example:

{
    "data": {
        "success": 1,
        "status": "Addendum invitation sent to Partner!"
    },
    "errors": [],
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YeobhK72bvPcGuKpIGBV43CLA0/ew3f32vvfbcDMZPMJ2upJzzPiWPpwqgrzqgrYuylZFVYdIxxxjTysIR2C7iIMdzNV9aw=="
    }
 }

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: success Indicates the success of the operation . boolean
: status Specifies the status of the operation. string
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array
POST
https://supply-xml.booking.com/contracts-api/partners/resend-addendum

The POST /partners/resend-addendum request enables you to resend the addendum to the Accommodation Partner with a link to the Booking.com contracting tool. The Accommodation Partner must sign the contract before you can set a property in the additional country as open and bookable, so use this endpoint as a reminder to the Accommodation Partner.

Body parameters

The following table describes what elements you must add as body parameters:

Element Description Type Required/Optional Notes
legal_contact_email Specifies the Accommodation Partner's legal contact email. string required The system sees this email as the unique identifier for the Accommodation Partner.
is_test Indicates whether you want to resend addendum to a (0) non-test Accommodation Partner or (1) a test Accommodation Partner. boolean optional

Request body example

The following is a request body example:

{
    "legal_contact_email": "don.giovanni@hotel.com"
   }

Response body example

The following is a successful response body example:

{
    "data": {
        "status": "Addendum invitation sent to Partner!",
        "success": 1
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YV3xmhN2gmpeH0l6WH5MTP66GghfYneDyb0q9aiC+oxTvdXEQn3f/ZXD0fE1azHNI80n+4AYvSlKNuaXmnQWfWwhR6rkaT7vDIHiRJoRmn5AjlIOgQIdG6L1jvDnofcQN4ZrP62t5pq0"
    }
}

Response body elements

The following table describes the response elements:

Element Description Type Notes
data Contains the response data. object
: success Indicates the success of the operation . boolean
: status Specifies the status of the operation. string
meta Contains the response meta data. object
: ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array