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": "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": "Waddington Bloem",
        "job_title": "Administration Employee",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31002666661",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "test@booking.com"
    },
    {
      "contact_profiles": [
        {
          "type": "general"
        }
      ],
      "address": {
        "city_name": "Amsterdam",
        "country_code": "NL",
        "postal_code": "1011 DL",
        "address_line": "New Straat 456",
        "language_code": "en-gb"
      },
      "contact_person": {
        "gender": "male",
        "name": "Bensen Clay",
        "job_title": "Administration Employee",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31002666661",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "tests@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": "Waddington Bloem",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31002666661",
            "phone_tech_type": "1",
            "extension": "1"
          }
        ],
        "email": "test@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "general"
          }
        ],
        "address": {
          "city_name": "Amsterdam",
          "country_code": "NL",
          "postal_code": "1011 DL",
          "address_line": "New Straat 456",
          "language_code": "en-gb"
        },
        "contact_person": {
          "gender": "male",
          "name": "Bensen Clay",
          "job_title": "Administration Employee",
          "language_code": "en-gb"
        },
        "phones": [
          {
            "phone_number": "+31002666661",
            "phone_tech_type": "1",
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      }
    ]
  },
  "meta": {
    "ruid": "250r05g4-5fa6-3689-a0f5-xx3416854532"
  }
}

Step 3 - Add another contact

Add another contact using the same PUT endpoint as Step 1 but change the content in the body to specify details of a different contact. 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": "invoices"
        }
      ],
      "address": {
        "city_name": "Amstelveen",
        "country_code": "NL",
        "postal_code": "1183 DL",
        "address_line": "Korvet 123",
        "language_code": "en-gb"
      },
      "contact_person": {
        "gender": "female",
        "name": "Lieke Bol",
        "job_title": "Administration Employee",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31002666661",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "test-person1@booking.com"
    },
    {
      "contact_profiles": [
        {
          "type": "general"
        }
      ],
      "address": {
        "city_name": "Rotterdam",
        "country_code": "NL",
        "postal_code": "2636 KA",
        "address_line": "Albert Verweylaan 456",
        "language_code": "en-gb"
      },
      "contact_person": {
        "gender": "male",
        "name": "Jan Van Vincent",
        "job_title": "Administration Employee",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31021677111",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "tests-person2@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

If you have already created a contact successfuly in Step 1, update the details of the contact using the following sample:

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
`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": "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": "+31002666661",
          "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 456",
        "language_code": "en-gb"
      },
      "contact_person": {
        "gender": "male",
        "name": "Kevin Mcmartin",
        "job_title": "General Manager",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31002666661",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "tests@booking.com"
    }
  ]
}

Response body

The following is a response body example:

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

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 all existing contacts except the one in the body.

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
`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": "general"
        }
      ],
      "address": {
        "city_name": "Rotterdam",
        "country_code": "NL",
        "postal_code": "2636 KA",
        "address_line": "Albert Verweylaan 456",
        "language_code": "en-gb"
      },
      "contact_person": {
        "gender": "male",
        "name": "Jan Van Vincent",
        "job_title": "Administration Employee",
        "language_code": "en-gb"
      },
      "phones": [
        {
          "phone_number": "+31021677111",
          "phone_tech_type": "1",
          "extension": "1"
        }
      ],
      "email": "tests-person2@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@booking.com 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.