Managing contact details

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

This topic covers how to:

Create contact details
Update/overwrite/delete contact details
Retrieve contact details

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	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	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.