HotelDataHub - Contacts — HotelDataHub API Docs

Table of contents¶

Introduction
Use cases
Available methods
Parameter table
Examples
Request (POST-PATCH)
Response (POST-PATCH)
Request (GET)
Response (GET)

Introduction¶

This article covers the API requests related to Contacts.

Create a contact
Update a contact
List and filter contacts

Endpoint: https://app.hoteldatahub.io/api/v1/contacts/

Swagger: https://app.hoteldatahub.io/swagger/#/contacts

Use cases¶

The contact management endpoint is very useful for bringing new contacts into Fideltour from different sources. For contacts that already exist, it lets you enrich the information in their profile, improving the quality of the database. Multiple data sources let you gather different information that is then centralized in Fideltour.

Booking engine¶

Using this endpoint from a booking engine lets you retrieve the contact information of a guest who has made a booking through the hotel or chain's website. This way, even before the future guest arrives at the hotel, Fideltour already has their contact details and you can start communicating with them.

PMS¶

Information coming from a PMS is very valuable for Fideltour, since many data sources centralize their information there. It also lets you obtain contact information for other guests, beyond the person who made the booking, growing the size of your database thanks to this connection.

Wi-Fi and other platforms¶

A hotel may have other platforms or cloud services that collect information about its users, and can send it to Fideltour to enrich the database and improve marketing campaigns and informational communications about the hotel's services.

Available methods¶

All the methods and filters available for working with contacts can be found here. This article focuses on the following:

GET: Retrieve data for one or more contacts
POST: Create a new contact
PATCH: Update the data of an existing contact

Parameter table¶

Field	Type	Req.	Description
`email`	String	Yes	Contact's email, unique field, used as the contact's identifier.
`name`	String	No	Contact's first name
`surname`	String	No	Contact's last name
`phone1`	String	No	Contact's phone number
`birthday`	Date YYYY-MM-DD	No	Date of birth
`gender`	Integer	No	Gender: • 0 = not specified (default) • 1 = male • 2 = female • 3 = non-binary • 4 = genderfluid • 5 = prefer not to say
`address`	String	No	Address
`post_code`	String	No	Postal code
`zone`	String	No	Two options: • Identifier of an already-created zone. • Name of the zone. The system creates it if none exists with that name
`town`	String	No	Two options: • Identifier of an already-created town. • Name of the town. The system creates it if none exists with that name
`province`	String	No	Two options: • Identifier of an already-created province. • Name of the province. The system creates it if none exists with that name
`country`	String	No	ISO 3166-1 alpha-2
`language`	String	No	ISO 639-1 Code
`identification_document_type`	Numeric	No	Identity document type. • 0 = Other • 1 = National ID • 2 = Foreigner ID • 3 = Passport
`identification_number`	String	No	Identity document number.
`business_name`	String	No	Company name
`work_place`	String	No	Job title
`business_address`	String	No	Company address
`fiscal_address`	String	No	Fiscal address
`notes`	String	No	Notes
`custom_tags`	List of Strings	No	Two options: • Identifier of an already-created tag. • Name of the tag. The system creates it if none exists with that name
`source`	Integer	Yes (POST) No (PATCH)	Source of the contact. • 0 = PMS • 1 = Wifi Login • 2 = Facebook • 3 = Web / Booking Engine • 4 = Other • 5 = Import • 6 = Newsletter form • 7 = Contact form • 8 = Guest Portal • 9 = Pre-Checkin • 10 = Chatbot • 11 = Concierge • 12 = Call Center • 13 = Landing Form • 14 = Intranet • 15 = PMS Other • 16 = PMS Restaurant • 17 = PMS SPA • 18 = BE Other • 19 = BE Restaurant • 20 = BE SPA • 21 = API • 22 = Zapier / Make • 23 = SDK / Hotel App • 24 = Corporate CRM • 25 = Hotel Website • 26 = Venues Website • 27 = Restaurant Website
`custom_fields`	Object	No	Key-value dictionary with the contact's custom fields. The keys are the identifiers of the fields defined in Fideltour. Example: `{"cf_vip": true, "cf_deeplink": "https://..."}`
`external_object_id`	String	No	Contact identifier in the external system (PMS, BE, etc.). Used as an alternative search criterion to email for finding and deduplicating contacts in Fideltour.
`subscribed`	Boolean	No	Indicates whether the contact is subscribed to receive mailings. • True = Subscribed • False = Not subscribed (default)

Examples¶

Below are some examples of creating, updating and viewing contacts.

Request (POST-PATCH)¶

The following example shows a request to create (POST) or update (PATCH) the contact pablo@hdh.com.

PROTOCOL: HTTP/1.1 METHOD: POST/PATCH HOST/ENDPOINT: https://app.hoteldatahub.io/api/v1/contacts/ HEADERS:

Content-type: application/json
Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY:

{
    "email": "pablo@hdh.com",
    "birthday": "1976-04-18",
    "phone1": "651442233",
    "gender": 2,
    "address": "Calle los olivos",
    "province": "Madrid",
    "town": "Madrid",
    "zone": "Sol",
    "post_code": "28013",
    "language": "es",
    "country": "ES",
    "name": "Pablo",
    "surname": "Mir",
    "identification_document_type": 1,
    "identification_number": "01234567Z",
    "source": 1,
    "notes": "Very demanding",
    "work_place": "Palma",
    "business_name": "Customia",
    "business_address": "Calle de las soluciones industriales 25",
    "fiscal_address": "Calle de las soluciones industriales 25",
    "custom_tags": ["VIP Customer", "Tourist"],
    "custom_fields": {"cf_vip": true},
    "subscribed": false
}

Note: the Boolean values true and false can also be sent as integers 1 and 0.

Response (POST-PATCH)¶

For a 200 or 201 response, the JSON you receive has the following structure:

{
   "id": 9999999,
   "business_name": "Customia",
   "work_place": "Palma",
   "business_address": "Calle de las soluciones industriales 25",
   "fiscal_address": "Calle de las soluciones industriales 25",
   "language": "es",
   "country": "ES",
   "created_at": "2022-01-01T12:12:12.654321",
   "level_name": "",
   "loyalty_card_number": null,
   "name": "Pablo",
   "surname": "Mir",
   "email": "pablo@hdh.com",
   "email_status": 0,
   "phone1": "651442233",
   "gender": 2,
   "identification_document_type": 1,
   "identification_number": "01234567Z",
   "birthday": "1976-04-18",
   "address": "Calle los olivos",
   "post_code": "28013",
   "source": 1,
   "notes": "Very demanding",
   "photo": null,
   "subscribed": false,
   "unsubscribe_reason": null,
   "date_subscribed": "2022-01-01T12:12:12.654321",
   "modification_date_subscribed": null,
   "is_active": true,
   "points": 0,
   "value": 0,
   "review": null,
   "total_bookings": 0,
   "level_points": 0,
   "loyalty_custom_tag_timestamp": null,
   "is_profile_completed": false,
   "last_level_review": null,
   "kicked_out_loyalty": null,
   "province": 1,
   "town": 2,
   "zone": 3,
   "level": null,
   "custom_tags": [4, 5],
   "custom_fields": {"cf_vip": true},
   "hotels": []
}

Request (GET)¶

The GET method allows the following:

List contacts based on applied filters, which can be found in: See on Swagger
Get the data for a contact by passing its ID as a URL parameter: https://app.hoteldatahub.io/api/v1/contacts/{id}/

Note: The contact {id} is always numeric. A path with a non-numeric value (for example /contacts/entries/) does not exist and returns 404. If the ID is numeric but the contact does not exist, the response is also 404.

Note: When retrieving a contact by ID (/contacts/{id}/), the response includes the extra field custom_tags_names with the names of the tags corresponding to the custom_tags IDs.

Requesting a contact's custom_fields¶

The contact list endpoint (GET /api/v1/contacts/) supports two query string parameters to request custom fields:

Parameter	Description
`?fields=custom_fields`	Returns all of the contact's active custom fields.
`?custom_fields=key1,key2`	Returns only the custom fields specified by key, comma-separated. It doesn't need to be combined with `?fields=custom_fields`.

Example:

GET https://app.hoteldatahub.io/api/v1/contacts/?email__iexact=pablo@hdh.com&custom_fields=cf_vip,cf_deeplink

PROTOCOL: HTTP/1.1 METHOD: GET HOST/ENDPOINT: https://app.hoteldatahub.io/api/v1/contacts/?email__iexact=pablo@hdh.com HEADERS:

Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

BODY: Since this is a GET request, no data is included in the request body, as it's included in the URL instead.

Response (GET)¶

{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
       {
           "id": 7778735,
           "business_name": null,
           "work_place": "Palma",
           "business_address": null,
           "fiscal_address": "Calle de las soluciones industriales 25",
           "language": "ES",
           "country": "ES",
           "created_at": "2022-12-21T16:40:20.681955",
           "level_name": "",
           "loyalty_card_number": null,
           "name": "Pablo",
           "surname": "Mir",
           "email": "pablo@hdh.com",
           "email_status": 0,
           "phone1": "651442233",
           "gender": 2,
           "identification_document_type": 1,
           "identification_number": "01234567Z",
           "birthday": "1976-04-18",
           "address": "Calle los olivos",
           "post_code": "07006",
           "source": 1,
           "notes": "Very demanding",
           "photo": null,
           "subscribed": false,
           "unsubscribe_reason": null,
           "date_subscribed": "2022-12-21T16:40:20.681955",
           "modification_date_subscribed": null,
           "is_active": true,
           "points": 0,
           "value": 0,
           "review": null,
           "total_bookings": 0,
           "level_points": 0,
           "loyalty_custom_tag_timestamp": null,
           "is_profile_completed": false,
           "last_level_review": null,
           "kicked_out_loyalty": null,
           "province": 1,
           "town": 2,
           "zone": 3,
           "level": null,
           "custom_tags": [4, 5],
           "custom_tags_names": ["VIP Customer", "Tourist"],
           "custom_fields": {"cf_vip": true},
           "hotels": []
       }
   ]
}