Self-certification tutorial: Contacts API

In this Self-assessment tutorial, you will use the Contacts API to:

Create a contact
Read back the contact
Add another contact
Update a contact/change contact details
Delete a contact
Contact connectivity support to validate your integration and enable live/production property access

Who is this for?

You should follow this if you are a developer who has completed the integration of Contact API’s endpoints and is looking to start using this with live properties in production.

Before you start

You will need to use an existing test property which was either created by Property API or found in the list of test properties on the provider portal.

Step 1 - Create a Contact

Create a contact for a test property within your system that will trigger a request to the create contacts endpoint listed below. Save the RUID to include in your report to connectivity support (see below).

Sample request

PUT
https://supply-xml.booking.com/contacts-api/properties/{propertyID}/contacts

Header parameter

The following table describes the elements you can add in the header:

Header	Description	Type	Required/ Optional	Notes
`Content-Type: application/json`	Specifies the expected content type.	string	required
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body

The following is a request body example:

{
    "contacts": [
      {
        "contact_profiles": [
          {
            "type": "reservations"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Bensen Jill",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests2@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "invoices"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lucy Gilean",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "general"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Kevin Mcmartin",
          "job_title": "General Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "parity"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Waddington Hommes",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests1@booking.com"
      }
    ]
  }

Response body

The following is a response body example:

{
  "warnings": [],
  "meta": {
    "ruid": "5rw83de5-54tt-45ad-a75c-af451309f764"
  }
}

Step 2 - Read a contact

Using your system, trigger a read request of the contact you have just created. Save the RUID to include in your report to connectivity support.

Sample request

GET
https://supply-xml.booking.com/contacts-api/properties/{propertyID}/contacts

Header parameter

The following table describes the elements you can add in the header:

Header	Description	Type	Required/ Optional	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Response body

The following is a response body example:

{
    "data": {
        "contacts": [
            {
                "contact_profiles": [
                    {
                        "type": "invoices"
                    }
                ],
                "address": {
                    "city_name": "Amsterdam",
                    "country_code": "NL",
                    "postal_code": "1011 DL",
                    "address_line": "New Straat 123",
                    "language_code": "en-gb"
                },
                "contact_person": {
                    "gender": "female",
                    "name": "Lucy Gilean",
                    "job_title": "Administration Employee",
                    "language_code": "en-gb"
                },
                "phones": [
                    {
                        "phone_number": "+31626666611",
                        "phone_tech_type": 1,
                        "extension": "1"
                    }
                ],
                "email": "tests@booking.com"
            },
            {
                "contact_profiles": [
                    {
                        "type": "reservations"
                    }
                ],
                "address": {
                    "city_name": "Amsterdam",
                    "country_code": "NL",
                    "postal_code": "1011 DL",
                    "address_line": "New Straat 123",
                    "language_code": "en-gb"
                },
                "contact_person": {
                    "gender": "male",
                    "name": "Bensen Jill",
                    "job_title": "Administration Employee",
                    "language_code": "en-gb"
                },
                "phones": [
                    {
                        "phone_number": "+31626666611",
                        "phone_tech_type": 1,
                        "extension": "1"
                    }
                ],
                "email": "tests2@booking.com"
            },
            {
                "contact_profiles": [
                    {
                        "type": "parity"
                    }
                ],
                "address": {
                    "city_name": "Amsterdam",
                    "country_code": "NL",
                    "postal_code": "1011 DL",
                    "address_line": "New Straat 123",
                    "language_code": "en-gb"
                },
                "contact_person": {
                    "gender": "female",
                    "name": "Waddington Hommes",
                    "job_title": "Administration Employee",
                    "language_code": "en-gb"
                },
                "phones": [
                    {
                        "phone_number": "+31626666611",
                        "phone_tech_type": 1,
                        "extension": "1"
                    }
                ],
                "email": "tests1@booking.com"
            },
            {
                "contact_profiles": [
                    {
                        "type": "general"
                    }
                ],
                "address": {
                    "city_name": "Amsterdam",
                    "country_code": "NL",
                    "postal_code": "1011 DL",
                    "address_line": "New Straat 123",
                    "language_code": "en-gb"
                },
                "contact_person": {
                    "gender": "male",
                    "name": "Kevin Mcmartin",
                    "job_title": "General Manager",
                    "language_code": "en-gb"
                },
                "phones": [
                    {
                        "phone_number": "+31626666611",
                        "phone_tech_type": 1,
                        "extension": "1"
                    }
                ],
                "email": "tests@booking.com"
            }
        ]
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "2d6a81af-6550-4ac7-b571-9660f2ecf164"
    }
}

Step 3 - Add another contact

Add another contact using the same PUT endpoint as Step 1. This endpoint overwrites all existing contacts, so send the four contacts from Step 1 together with the new availability contact. A GET request after this step returns five contacts. Save the RUID to include in your report to connectivity support (see below).

Sample request

PUT
https://supply-xml.booking.com/contacts-api/properties/{propertyID}/contacts

Header parameter

The following table describes the elements you can add in the header:

Header	Description	Type	Required/ Optional	Notes
`Content-Type: application/json`	Specifies the expected content type.	string	required
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body

The following is a request body example:

{
    "contacts": [
      {
        "contact_profiles": [
          {
            "type": "reservations"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Bensen Jill",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests2@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "invoices"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lucy Gilean",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "general"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Kevin Mcmartin",
          "job_title": "General Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "parity"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Waddington Hommes",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests1@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "availability"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lieke Bol",
          "job_title": "Reservations Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests3@booking.com"
      }
    ]
  }

Response body

The following is a response body example:

{
  "warnings": [],
  "meta": {
    "ruid": "frw83de5-54tt-45ad-a75c-ab623309f711"
  }
}

Step 4 - Update or overwrite the details of a contact

To update the details of a contact, send the full contact list again with the changed values. In the following sample, the job title of the invoices contact (Lucy Gilean) changes to Finance Manager. Send all five contacts. The contacts you omit are deleted.

Sample request

PUT
https://supply-xml.booking.com/contacts-api/properties/{propertyID}/contacts

Header parameter

The following table describes the elements you can add in the header:

Header	Description	Type	Required/ Optional	Notes
`Content-Type: application/json`	Specifies the expected content type.	string	required
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body

The following is a request body example:

{
    "contacts": [
      {
        "contact_profiles": [
          {
            "type": "reservations"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Bensen Jill",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests2@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "invoices"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lucy Gilean",
          "job_title": "Finance Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "general"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Kevin Mcmartin",
          "job_title": "General Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "parity"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Waddington Hommes",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests1@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "availability"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lieke Bol",
          "job_title": "Reservations Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests3@booking.com"
      }
    ]
  }

Response body

The following is a response body example:

{
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "111b3h37-ca0a-415a-89e2-fc451300325f"
    }
}

Step 5 - Delete a contact

You can delete a contact by using the PUT method again but omitting the details of the contact that needs to be deleted in the request body. Save the RUID to include in your report to connectivity support (see below). The sample below deletes the availability contact (Lieke Bol) by sending the other four contacts. Always include the general contact.

Sample request

PUT
https://supply-xml.booking.com/contacts-api/properties/{propertyID}/contacts

Header parameter

The following table describes the elements you can add in the header:

Header	Description	Type	Required/ Optional	Notes
`Content-Type: application/json`	Specifies the expected content type.	string	required
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Currently supports the value: 1.0

Request body

The following is a request body example:

{
    "contacts": [
      {
        "contact_profiles": [
          {
            "type": "reservations"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Bensen Jill",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests2@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "invoices"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Lucy Gilean",
          "job_title": "Finance Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "general"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Kevin Mcmartin",
          "job_title": "General Manager",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "parity"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 123",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "female",
          "name": "Waddington Hommes",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31626666611",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests1@booking.com"
      }
    ]
  }

Response body

The following is a response body example:

{
  "warnings": [],
  "meta": {
    "ruid": "cbw22de3-54tt-45ad-a75c-abc23309f822"
  }
}

Step 6 - Send the RUIDs to Booking.com

Send via your organisation’s domain email the RUID values obtained in the response bodies of the PUT and GET requests to Connectivity Support for validation and certification.

Email template

I would like to be certified for production use of Contacts API. Please find the RUIDs for all of the steps in the tutorial.

I look forward to hearing from you.