Writing profiles
Send the real source with every attribute
Each attribute carries afrom field naming who provided the information: agent, guest, pms, or system. Set it to the actual origin of the data you send rather than a constant: the profile’s value comes from knowing where each piece of information came from.
Prefer differential updates
Reach forPATCH when you add information: array attributes append instead of being replaced, so you never erase an email or a phone another source contributed. Use PUT when you intend to override attributes, and "strict": true only when you intend to rebuild the whole profile: it overrides everything, including the attributes absent from your payload.
Check what an update stored
An attribute whose value the API rejects is dropped without changing the status code, and the response carries no body, so a200 OK tells you nothing about what landed. When the write matters, follow it with Get a guest and compare. Validate values against the documented enums on your side before sending them, since that check is the only one you control. See Responses.
Finding guests
Search for screens, browse for volume
Search guests fits interactive screens: it returns the first matches of a query, up to 100, and each document carries the guest plus the booking when the query touches stay criteria. It is not suitable for large result sets. To walk through a high volume of guests, use Browse guests, which returns anafterKey cursor you send back to get the next page.
Count before you pull
Count guests returns the number of guests matching a query, with anaccurate flag saying whether the number is exact or an estimate. Run it before a heavy export to size the work, or to display a figure without fetching a single profile.
Build queries from the listed pairs
Which operators a field accepts depends on the field: a date takes the day keywords, a text field the contains operators, a number the comparisons. Build each criterion from the pairs the Search criteria page lists, and validate them on your side before sending, as you would an enum value.Duplicates
Score before you merge
Compute merge confidence measures how close a set of profiles is, on the same scale as the merge threshold, and hands the score back through its task. Run it first when the decision is not obvious, and keep the score: it is what tells you whether a threshold of 75 is right for your data.Set the threshold to match your tolerance
Merge guests compares all the listed guests and merges them only when the similarity threshold is reached for every comparison (the default is 75). Raise the threshold when you would rather leave a duplicate in place than merge two different people. The merged profile keeps the identifiers of its source profiles incomposedWith, and Unmerge a guest splits it back apart, so a merge is recoverable.
Wait for the task before reading the result
Both calls run in the background and answer with alocation header pointing at a task. A 200 on the call itself means the work was accepted, nothing more: read the task until its status settles before treating the merge as done. See Responses.
Expect redirects on merged guests
After a merge, reading a source guest returns the merged profile. Passredirect=false to read the original instead, and expand=true to inspect the source profiles behind a merged one.
Personal data
Honour the opt-out flags
A profile carries anoptedOut flag per communication channel, each one absent until something records it. Read them before sending any communication to a guest, and handle the absent case explicitly. Write them when a guest changes their preferences on your side, so every system connected to the entity sees the same choice.
Anonymise instead of deleting
Guest profiles are anonymised rather than deleted: Anonymise a guest is the way to honour a guest’s request to have their data removed. Trigger it from your own privacy workflow so the profile is anonymised in the CRM at the same time as in your systems.Store identifiers, not copies
Keep the guest identifier and the entity identifier on your side and read the profile when you need it, rather than replicating personal data in your own database. Every copy you avoid is one less store to protect and purge.Resilience
Retry transient errors with care
Retry transient failures (network blips,408, and occasional 5xx) on GET calls with exponential backoff. Create a guest is not idempotent: retrying it can create a duplicate profile, so when a create times out, search for the guest before sending the call again.
Plan for slow or unreachable calls
Decide upfront how long your interface waits for a response and what it shows past that point. Make the choice deliberately rather than letting the network decide.Log the error details
When a call fails, capture thecode, message, and data fields from the error body in your logs. They let the partnership team pinpoint the failure when you report it.