Guide: sync customers with a CRM

Customers are contacts in HQ's Contacts module (see HQ concepts and glossary).
Contacts are grouped in contact categories, and bookings save their customers by default in the category set as the default contact category for customers in your car rental settings.

Step 1 - Find the category and its fields

GET /contacts/categories lists the contact categories with their IDs.
GET /fields?item_type=contacts.<category_id> lists the fields of one category, and GET /fields?item_type=contacts the fields every contact has (see Custom fields and item types).
All three lists return 10 per page by default, so send a larger limit or read every page.
Map each CRM field to a field ID once.

Step 2 - Read contacts

Parameter	Meaning
`page`, `limit`	Pagination.
`updated_since`	Only contacts changed at or after this UTC time, `YYYY-MM-DD HH:mm:ss`.
`global_search`	Free-text search.
`filters`	Filters on `first_name`, `last_name`, `email`, `phone_number`, `street`, `city`, `zip`, `country`, `driver_license` or `field_<id>` (see Filtering and incremental sync).

Contacts come newest first, and the response is the pagination object itself, without success.
GET /contacts/categories/{category_id}/contacts/{id} returns one contact under contact.

Step 3 - Create and update contacts

Create: POST /contacts/categories/{category_id}/contacts

Update: PUT /contacts/categories/{category_id}/contacts/{id}

Send each value as field_<id>, plus:

contact_entity: person or company.
If the category has its own entity field, send the value in that field's field_<id> instead.

external_contact_type and external_contact_id: the name of your system and the contact's ID in it, for example hubspot and 1234567.

The field IDs above are examples; use the IDs of your account.
On update, the fields you do not send keep their value (see Custom fields and item types for how empty values and permissions are handled).
The response returns the saved contact under contact; store its id in your CRM.

Step 4 - Book for a known customer

Bookings can find a contact by your CRM ID, so a returning customer is not created again.
Send external_contact_type and external_contact_id to POST /car-rental/reservations/customer: HQ updates the contact that has that pair, or creates it the first time.
You can also send the HQ contact ID as customer_id to POST /car-rental/reservations/confirm.

To list a customer's reservations by your CRM ID, filter GET /car-rental/reservations on customers.external_contact_id:

Step 5 - Merge duplicates

POST /contacts/{id}/merge with contact_ids, a comma-separated list such as 12,15, merges those contacts into the contact id and deletes them, so point their CRM records to the kept contact.
The kept contact keeps only its own external_contact_type and external_contact_id; if your CRM ID was on a merged contact, set it on the kept contact with PUT /contacts/categories/{category_id}/contacts/{id}.

Things to know

The contacts list cannot be filtered on external_contact_id, so keep the mapping between HQ and CRM IDs in your system.

POST /car-rental/reservations/customer without contact_id, contact_uuid or the external pair creates a new contact on every call, even when one with the same email exists.

When POST /car-rental/reservations/customer updates an existing contact, the fields you leave out are cleared.
ignore_empty_fields keeps the fields shared by all contacts, but the fields of the customer category are still cleared.
To change a customer's details outside a booking, use the Contacts endpoints.

Guide: sync customers with a CRM

Step 1 - Find the category and its fields#

Step 2 - Read contacts#

Step 3 - Create and update contacts#

Step 4 - Book for a known customer#