Managing contracting flow

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

Quick actions

• Creating a legal entity ID
• Retrieving contract status and legal details with legal contact email
• Retrieving contract status and legal details with legal entity ID
• Resending email with link to contracting tool
• Update an existing contract
• Resending updated contract email with link to contracting tool

Creating a legal entity ID

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 successful 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:

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:

Retrieving contract status and legal details with legal contact email

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:

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:

Retrieving contract status and legal details with legal entity ID

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:

Resending email with link to contracting tool

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:

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:

Update an existing contract

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

The POST /partners/addendum request enables you to update an existing contract. You should use this if you want to add additional countries to the contract or update the contract contact details including contact name, address and company name.

A successful 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) or where they change their contact details.

Body parameters

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

Request body example

The following is a request body example:

{
  "additional_countries": [
    "be"
  ],
  "le_id": "1234"
}

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:

Resending updated contract email with link to contracting tool

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

The POST /partners/resend-addendum request enables you to resend the updated contract 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 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:

Request body example

The following is a request body example:

{
  "le_id": "1234"
}
   
   

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: