Post-stay profile enrichment

What a guest tells you after a stay is worth more than what they filled in before it: the language they actually answer in, the floor they asked to change, the review they left. That knowledge usually stops inside the tool that collected it. Writing it back to the guest profile puts it in front of the next hotel that welcomes them.

How it works

Three steps, each an API call:

Read the stays with Browse bookings, which pairs every booking with the guest it belongs to.
Read the profile with Get a guest, for the sourced attributes the index does not carry.
Write back with Partially update a guest, which appends to array attributes instead of replacing them.

The examples reuse the bearer token from the Quick start. Replace {entityId} with your entity.

Read the stays

Browse bookings lives on the bookings service, so its path starts with /api/bookings-manager/. It paginates with limit and offset, and the response carries a total, so the first call also sizes the work. The query below keeps the confirmed stays that ended in August 2026. With > and <, departure takes a plain YYYY-MM-DD date, so the API filters the window for you.

curl --request POST \
  --url 'https://{apiBaseUrl}/api/bookings-manager/entities/{entityId}/bookings/browse' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 100,
    "offset": 0,
    "query": {
      "logic": "AND",
      "criteria": [
        {"logic": "AND", "criteria": [
          {"field": "bookingstatus", "operator": "=", "value": "confirmed"},
          {"field": "departure", "operator": ">", "value": "2026-08-01"},
          {"field": "departure", "operator": "<", "value": "2026-09-01"}
        ]}
      ]
    }
  }'

{
  "bookings": [
    {
      "booking": {
        "guestId": "55468764-64be-4fc1-a43f-e37239e012bf",
        "arrival": "2026-08-24T15:00:00Z",
        "departure": "2026-08-27T11:00:00Z",
        "stayLength": 3,
        "paxAdults": 2,
        "status": "confirmed"
      },
      "guest": {
        "id": "55468764-64be-4fc1-a43f-e37239e012bf",
        "firstname": "Martin",
        "emails": "martin.dupont@example.com"
      }
    }
  ],
  "total": 148
}

Move the window forward on each run. The Search criteria page lists the fields and operators available to narrow the stays further.

Write back what you learned

Use PATCH, not PUT. On an array attribute it appends: the language the guest answered in joins the one the PMS wrote instead of erasing it, and a note lands next to the ones the staff already took. Set from to the real origin of what you write: guest for what the guest told you, agent for what a human recorded.

curl --request PATCH \
  --url 'https://{apiBaseUrl}/api/guestprofile/entities/{entityId}/guests/55468764-64be-4fc1-a43f-e37239e012bf' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "languages": [{"value": "fr", "from": "guest"}],
    "notes": [{"value": "Asked for a quiet room away from the lift.", "from": "agent"}]
  }'

const guestId = "55468764-64be-4fc1-a43f-e37239e012bf";

await fetch(
  `https://{apiBaseUrl}/api/guestprofile/entities/${entityId}/guests/${guestId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      languages: [{ value: "fr", from: "guest" }],
      notes: [{ value: "Asked for a quiet room away from the lift.", from: "agent" }],
    }),
  }
);

// the response is empty, so read the profile back when the write matters
const stored = await (
  await fetch(
    `https://{apiBaseUrl}/api/guestprofile/entities/${entityId}/guests/${guestId}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  )
).json();

guest_id = "55468764-64be-4fc1-a43f-e37239e012bf"
url = f"https://{{apiBaseUrl}}/api/guestprofile/entities/{entity_id}/guests/{guest_id}"
headers = {"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"}

requests.patch(url, headers=headers, json={
    "languages": [{"value": "fr", "from": "guest"}],
    "notes": [{"value": "Asked for a quiet room away from the lift.", "from": "agent"}],
})

# the response is empty, so read the profile back when the write matters
stored = requests.get(url, headers=headers).json()

$guestId = '55468764-64be-4fc1-a43f-e37239e012bf';
$path = "/api/guestprofile/entities/$entityId/guests/$guestId";

$client->patch($path, ['json' => [
    'languages' => [['value' => 'fr', 'from' => 'guest']],
    'notes' => [['value' => 'Asked for a quiet room away from the lift.', 'from' => 'agent']],
]]);

// the response is empty, so read the profile back when the write matters
$stored = json_decode($client->get($path)->getBody(), true);

var guestId = "55468764-64be-4fc1-a43f-e37239e012bf";
var path = $"/api/guestprofile/entities/{entityId}/guests/{guestId}";

await client.PatchAsJsonAsync(path, new
{
    languages = new[] { new { value = "fr", from = "guest" } },
    notes = new[] { new { value = "Asked for a quiet room away from the lift.", from = "agent" } }
});

// the response is empty, so read the profile back when the write matters
var stored = await client.GetFromJsonAsync<JsonElement>(path);

String guestId = "55468764-64be-4fc1-a43f-e37239e012bf";
String url = "https://{apiBaseUrl}/api/guestprofile/entities/" + entityId + "/guests/" + guestId;

String body = """
    {
      "languages": [{"value": "fr", "from": "guest"}],
      "notes": [{"value": "Asked for a quiet room away from the lift.", "from": "agent"}]
    }
    """;

client.send(HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
    .build(), HttpResponse.BodyHandlers.ofString());

// the response is empty, so read the profile back when the write matters
HttpResponse<String> stored = client.send(HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Authorization", "Bearer " + accessToken)
    .GET().build(), HttpResponse.BodyHandlers.ofString());

Tailor the next message

Get a guest’s segments tells you which groups a profile belongs to, so the follow-up you send matches how the hotel already thinks about that guest. Read it before composing, and fall back to a neutral message when the list comes back empty.

curl --request GET \
  --url 'https://{apiBaseUrl}/api/guestprofile/entities/{entityId}/guests/55468764-64be-4fc1-a43f-e37239e012bf/segments' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Tips

PATCH is not idempotent. Array attributes append on every call, so a retried write can duplicate a note. Key your retries on your side, or read the profile before sending again.
Check the opt-out flags before any message. When a channel preference has been recorded, the profile carries it under optedOut; the attribute is absent until something sets it, so handle both cases. Read it on the profile rather than on your own copy, since another system may have changed it since your last sync.
Write the real source. A note stored as pms when a human wrote it makes the next partner trust it more than it deserves. The from field is what keeps a shared profile readable.

Browse bookings

Stays paired with their guest, page by page.

Partially update a guest

The append-style write.

Get started

Build

Resources

Post-stay profile enrichment

How it works

Read the stays

Write back what you learned

Tailor the next message

Tips

Browse bookings

Partially update a guest

​How it works

​Read the stays

​Write back what you learned

​Tailor the next message

​Tips

​Related

Browse bookings

Partially update a guest

How it works

Read the stays

Write back what you learned

Tailor the next message

Tips

Related