Beta version
This API endpoint is currently in beta. Make sure to direct any questions during the beta phase to your Booking.com contact person via the appropriate channels.
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. - When creating a contact of type
invoices
, you must add details in theaddress
parameter. - You can have multiple contacts for other contact profile types.
- 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.
- For a property to get to an open/bookable status, you must create at least one contact of type
general
andinvoices
.
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. | Required |
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 the following validations:
- There should be at least one contact of type
general
andinvoices
in the request - You can only update the details of the following contact types:
- General
- Invoices
- When updating a contact of type
invoices
, you must add details in theaddress
parameter. - 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 create and manage a property, see the Property Details API.