Home

Managing contact details

Use the contacts-api endpoint to create, update, retrieve and delete contact details.

This topic covers how to:

Creating contact details

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

You can create multiple contacts with different contact types but with the same contact details.

What are contact profile types?

Creating contact information with certain contact profile types is crucial to bringing a property to the open and bookable status.

You can create a contact based on the following contact profile types:

  • General: Primary point of contact for the property.
  • Invoices: Contact for accounts payable.
  • Reservations: Contact for reservations.
  • Availability: Contact for questions about availability.
  • Site_content: Contact for photos, descriptions and other website content.
  • Parity: Contact for pricing and rate topics.
  • Requests: Contact for special requests.
  • Central_reservations: Contact for central reservations. Applies to properties that manage reservations centrally.

Physical location is no longer a contact profile type. You can add physical location details using the property-api.

API validations

This section contains any validations that the API enforces when processing a create contacts request. Make sure your request meets these validations.

  • You can create at a maximum one contact details per property for the General contact type.
  • You can have multiple contacts for other contact profile types.
  • The invoice contact is the person who can be contacted to discuss invoices. This is not a mandatory contact type. It is located in the Property Settings API where you must specify the address for invoices.
  • You can update the contact details for the General contact type. Because this endpoint uses overlay, when updating other contact type details, make sure to also send the General contact details. Failing to send this in the update request will return an error.
  • Creating a contact of type invoices is optional. However, to make a property open and bookable, you must add address details for invoice contact using the Property settings (POST /property-settings) endpoint.
  • You cannot send the same contact details with identical contact types in a single request. However, you can send the same contact details with different contact types. In this case, the API creates one contact for all contact types.
  • The phone number is validated based on the formatting rules of the specified country code.

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

Path parameter

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

Value Description Type Required/
Optional		 Notes
{propertyID} value Specify the unique ID of the property where you want to create contact details. integer required

Request body parameters

The following table describes the elements you can add in the request body:

Element Attribute Description Type Required/
Optional		 Notes Root parameter in HDCN
> contacts Contains contact information. object required You must create one contact details for the General contact type. Note that you can create at a maximum only one contact detail per property for the General contact type. >>> ContactInfos
>> contact_profile_type Contains the contact type. object required - >>> ContactInfos > ContactInfo.ContactProfileType
type Specifies the type of contact. enumerated string required For a list of approved contact types, see ContactProfileType.
> address Contains the address details of the contact including country, city and postal code details. object optional for all contact types You can set only one address per contact type. >>> ContactInfos
city_name Species the name of the city, town, or village. string required if address is specified - >>> ContactInfos
state_prov_code Contains the State/province details. string optional The value specified in this field is not returned in the GET call. >>> ContactInfos
country_code Species the two-letter country code. enumerated string required if address is specified For more information on how to retrieve the country code details, see xml/countries endpoint. >>> ContactInfos
postal_code Specifies the postal/zip code. string required if address is specified Make sure the postal code is relevant to the country specified in the country_code. >>> ContactInfos
address_line Species the full street name and number. string required if address is specified Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters. >>> ContactInfos
language_code Species the Booking.com Language code for the address details. enumerated string required if address is specified For a list of supported language codes, see Booking.com Language Code table. >>> ContactInfos
> contact_person Contains the contact person's name, gender, spoken language and job title. string required - New field.
language_code Species the contact's spoken language(s). enumerated string required For a list of supported language codes, see Booking.com Language Code table. >>> ContactInfos
gender Specifies the contact's gender. enumerated string optional Accepts: Male, Female. Default: null. To set as empty, omit the entire attribute (instead of specifying ""). >>> ContactInfos
name Specifies the contact person's full name. string required - >>> ContactInfos
job_title Specifies the contact person's job title code. enumerated string optional For a list of supported job titles and their code, see Booking.com Job Title Code. By default, it is set to Unknown. >>> ContactInfos
> phones Contains the phone number information. object required - >>> ContactInfos
phone_number Specifies the international phone number. string required Follows the format: \+[0-9]+
The phone number is also validated based on the formatting rules of the specified country code.		 >>> ContactInfos
phone_tech_type Specifies the type of phone line/device. enumerated string required For a list of supported values, see PTT.
PhoneTechType 3 can have at most 3 entries.
PhoneTechType 1 and 5 can have at most 1 entry.
Extension can only be provided for PhoneTechType 1.		 >>> ContactInfos
extension The extension number that must be dialled in addition to the phone_number. string optional Only accepted when phone_tech_type="1". >>> ContactInfos
> email Contains the email address details. string required Make sure to specify a valid email address. >>> ContactInfos

Contact Profile Types

The contacts-api accepts the following values for the contact profile type. Each value corresponds to a similarly named heading on the Contacts page in our extranet.

A property must have all the required contact profiles before you can open it.

Value Description Required
general Primary point of contact for the property. Required
reservations Contact for reservations. Optional
invoices Contact for accounts payable. Optional
availability Contact for questions about availability. Optional
site_content Contact for photos, descriptions, and other website content. Optional
parity Contact for pricing and rate matters. Optional
requests Contact for special requests. Optional
central_reservations Contact for central reservations. Applies to properties that manage reservations from another location. Optional

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"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
warnings Contains any warnings in the response. object -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Overwriting contact details

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

Use the PUT contacts-api endpoint along with the property ID as a path parameter to:

  • overwrite existing contact details.
  • delete contact details by omitting them in the request.

Note that all existing contact details are lost and only the details sent in this request are added as new.

Retaining existing contact details

To retain any existing contact details that do not need an update, make sure to add them to the request.

API validations

This section contains any validations that the API enforces when processing an overwrite to contact details. Make sure your request meets these validations.

  • You can create at a maximum one contact details per property for the General contact type.
  • You can have multiple contacts for other contact profile types.
  • The invoice contact is the person who can be contacted to discuss invoices. This is not a mandatory contact type. It is located in the Property Settings API where you must specify the address for invoices.
  • You can update the contact details for the General contact type. Because this endpoint uses overlay, when updating other contact type details, make sure to also send the General contact details. Failing to send this in the update request will return an error.
  • Creating a contact of type invoices is optional. However, to make a property open and bookable, you must add address details for invoice contact using the Property settings (POST /property-api/properties/{{property_id}}/settings) endpoint.
  • You cannot send the same contact details with identical contact types in a single request. However, you can send the same contact details with different contact types. In this case, the API creates one contact for all contact types.
  • The phone number is validated based on the formatting rules of the specified country code.

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

Path parameter

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

Value Description Type Required/
Optional		 Notes
{propertyID} value Specify the unique ID of the property whose contact details you want to update. integer required

Request body parameters

The following table describes the elements you can add in the request body:

Element Attribute Description Type Required/
Optional		 Notes Name in HDCN
> contacts Contains contact information. object required You must create one contact details for the General contact type. Note that you can create at a maximum only one contact detail per property for the General contact type. >>> ContactInfos
>> contact_profile_type Contains the contact type. object required - >>> ContactInfos > ContactInfo.ContactProfileType
type Specifies the type of contact. enumerated string required For a list of approved contact types, see ContactProfileType.
> address Contains the address details of the contact including country, city and postal code details. object optional for all contact types You can set only one address per contact type. >>> ContactInfos
city_name Species the name of the city, town, or village. string required if address is specified - >>> ContactInfos
state_prov_code Contains the State/province details. string optional The value specified in this field is not returned in the GET call. >>> ContactInfos
country_code Species the two-letter country code. enumerated string required if address is specified For more information on how to retrieve the country code details, see xml/countries endpoint. >>> ContactInfos
postal_code Specifies the postal/zip code. string required if address is specified Make sure the postal code is relevant to the country specified in the country_code. >>> ContactInfos
address_line Species the full street name and number. string required if address is specified Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters. >>> ContactInfos
language_code Species the Booking.com Language code for the address details. enumerated string required if address is specified For a list of supported language codes, see Booking.com Language Code table. >>> ContactInfos
> contact_person Contains the contact person's name, gender, spoken language and job title. string required - New field.
language_code Species the contact's spoken language(s). enumerated string required For a list of supported language codes, see Booking.com Language Code table. >>> ContactInfos
gender Specifies the contact's gender. enumerated string optional Accepts: Male, Female. Default: null. To set as empty, omit the entire attribute (instead of specifying ""). >>> ContactInfos
name Specifies the contact person's full name. string required - >>> ContactInfos
job_title Specifies the contact person's job title code. enumerated string optional For a list of supported job titles and their code, see Booking.com Job Title Code. By default, it is set to Unknown. >>> ContactInfos
> phones Contains the phone number information. object required - >>> ContactInfos
phone_number Specifies the international phone number. string required Follows the format: \+[0-9]+
The phone number is also validated based on the formatting rules of the specified country code.		 >>> ContactInfos
phone_tech_type Specifies the type of phone line/device. enumerated string required For a list of supported values, see PTT.
PhoneTechType 3 can have at most 3 entries.
PhoneTechType 1 and 5 can have at most 1 entry.
Extension can only be provided for PhoneTechType 1.		 >>> ContactInfos
extension The extension number that must be dialled in addition to the phone_number. string optional Only accepted when phone_tech_type="1". >>> ContactInfos
> email Contains the email address details. string required Make sure to specify a valid email address. >>> ContactInfos

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": "5rw83de5-54tt-45ad-a75c-af451309f764"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
warnings Contains any warnings in the response. object -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Retrieving contact details

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

Use the GET contacts-api endpoint along with the property ID to retrieve the contact details created for the property.

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

Path parameter

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

Value Description Type Required/
Optional		 Notes
{propertyID} value Specify the unique ID of the property to retrieve the contact details. integer required

Response body

The following is a response body example:

{
  "data": {
    "contacts": [
      {
        "contact_profiles": [
          {
            "type": "reservations"
          }
        ],
        "contact_id": 396227214,
        "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": "+31000666661",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests2@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "invoices"
          }
        ],
        "contact_id": 395775571,
        "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"
          }
        ],
        "contact_id": 395775570,
        "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": "+31002666661",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests@booking.com"
      },
      {
        "contact_profiles": [
          {
            "type": "parity"
          }
        ],
        "contact_id": 396227126,
        "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": "+31000666661",
            "phone_tech_type": 1,
            "extension": "1"
          }
        ],
        "email": "tests1@booking.com"
      }
    ]
  },
  "meta": {
    "ruid": "149r05d7-e256-3689-a0f5-rt3416851256"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
data Root element object
> contacts Contains contact information. object -
>> contact_profile_type Contains the contact type. enumerated string -
type Specifies the type of contact. enumerated string
> contact_id Contains a unique identifier for the contact integer New field.
> address Contains the address details of the contact including country, city and postal code details. object -
city_name Specifies the name of the city, town, or village. string -
state_prov_code Contains the State/province details. string -
country_code Specifies the two-letter country code. enumerated string -
postal_code Specifies the postal/zip code. string -
address_line Specifies the full street name and number. string -
language_code Specifies the Booking.com Language code for the address details. enumerated string -
> contact_person Contains the contact person's name, gender, spoken language and job title. string -
language_code Specifies the contact's spoken language(s). enumerated string -
gender Specifies the contact's gender. enumerated string -
name Specifies the contact person's full name. string -
job_title Specifies the contact person's job title code. enumerated string -
> phone Contains the phone number information. object -
phone_number Specifies the international phone number. string -
phone_tech_type Specifies the type of phone line/device. enumerated string -
extension The extension number that must be dialled in addition to the phone_number. string -
> email Contains the email address details. string -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Quick Actions


→ To learn more about the Contacts API use cases, see Contacts API implementation use cases.
→ To troubleshoot Contacts API errors, see Troubleshooting Contacts API error responses.
→ To create and manage a property, see the Property Details API.

Is this page helpful?    Yes   |    No