Casa Layer · Every guest, remembered.

The guest event log is the append-only history Casa Layer stores for a guest. Each row is one change to one entity. Use it to replay what Casa Layer saw. You can read the log at two grains:

Guest profile — one source system’s record
Master profile — the golden record after identity resolution

Both paths start with a PMS source ID. The event log does not accept source_id. Resolve the Casa Layer ID first. Then send that ID to GET /v1/events. Use a partner API credential. Do not use a personal API key for a third-party system.

What you need

Select these scopes on the credential:

Scope	Why you need it
`read:properties`	Property roster and integration roster
`read:guests`	Guest lookup by PMS `source_id`
`read:events`	The guest event log

You also need the PMS guest ID. Casa Layer stores it as source_id on the guest profile. If the guest lookup is empty, use the PMS reservation ID instead. See Searching for a master profile using PMS identifiers.

1. Create partner credentials

Create the credential in the Casa Layer app. See Partner API credentials for the full steps.

Open Integrations → Partner credentials → Custom Integration.
Name the credential.
Select read:properties, read:guests, and read:events.
Click Create credentials.
Copy the client ID and client secret.

Casa Layer shows the client secret once. Store it with the partner.

2. Get an access token

Exchange the client ID and client secret for a short-lived access token.

curl -X POST https://temperate-milestone-52.authkit.app/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Read access_token from the response. Cache it until exp. Do not mint a token on every Casa Layer call. Send the token as a bearer credential on every request below:

-H "Authorization: Bearer $ACCESS_TOKEN"

3. Get property context

List the properties in the credential’s group.

curl https://api.casa-layer.com/v1/properties \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Each row has an id and a name. Use id as X-Property-Id when you want one property only.

-H "X-Property-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7"

The property must belong to the credential’s group. A property outside the group returns 403. Skip the header to search the whole group.

4. Get integration IDs

A PMS source_id is unique only inside one integration. List the roster first.

curl https://api.casa-layer.com/v1/integrations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Each row is one source system mapped to a property:

Field	Use
`id`	The `integration_id` you send with `source_id`
`provider`	Source system slug, for example `mews` or `apaleo`
`name`	Display name of the connection
`property_id`	Property this mapping belongs to
`source_ref`	Source entity ID (for example a Mews Enterprise ID)
`status`	`pending`, `connected`, or `error`

Pick the row for the PMS and property you will query. Copy id.

GET /v1/guests rejects source_id without integration_id. The error is 400.

5. Resolve the guest from the PMS source ID

curl "https://api.casa-layer.com/v1/guests?source_id=mews-guest-8842&integration_id=1f2d6c4e-1b2a-4c3d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response is a list. A match has one row. No match has an empty data array.

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "property_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integration_id": "1f2d6c4e-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
      "master_profile_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "source_id": "mews-guest-8842",
      "first_name": "Ada",
      "surname": "Lovelace"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Read two Casa Layer IDs from the guest row:

Field	What it is
`id`	Casa Layer guest profile ID. Use this for the guest grain.
`master_profile_id`	Casa Layer master profile ID when the guest is clustered.
`source_id`	PMS guest ID you sent

If data is empty, that PMS may not store a guest source_id. Resolve the guest from a reservation instead. Then use the reservation’s guest_profile_id. If master_profile_id is null, identity resolution has not clustered this guest. You can still read the guest event log. You cannot read a master event log yet.

6. Read the event log

Send one filter. Do not send guest_profile_id and master_profile_id together. Both filters combine with AND.

Path A — guest profile (one source system)

Use the guest id from step 5. This log is one sub-profile only.

curl "https://api.casa-layer.com/v1/events?guest_profile_id=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Use this path when you want what one PMS said about the guest.

Path B — master profile (resolved guest)

Use master_profile_id from step 5. This log covers every clustered member sub-profile of that master.

curl "https://api.casa-layer.com/v1/events?master_profile_id=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Use this path when you want the full history for the real guest. The master filter matches guest profiles whose master_profile_id equals that ID. An unclustered guest does not match. If step 5 returned master_profile_id: null, use Path A. One guest source_id is enough for Path B. After you have the master ID, the log includes the other clustered sub-profiles too.

master_profile_id on GET /v1/events is a Casa Layer UUID. It is not a PMS ID.

Modes

GET /v1/events has two modes.

Mode	What you get
`timeline` (default)	Full change history, oldest first. Keyset-paginated.
`latest`	Latest delta slice per entity. One page. `next_cursor` is `null`.

latest is not a merged entity snapshot. It is the last observed change for each entity. rollup is a deprecated alias for latest. The response mode is always timeline or latest.

curl "https://api.casa-layer.com/v1/events?guest_profile_id=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d&mode=latest" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Walk a timeline with limit and cursor. Default limit is 100. The maximum is 500. See Pagination.

curl "https://api.casa-layer.com/v1/events?guest_profile_id=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d&limit=500" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Send the last next_cursor as cursor until next_cursor is null.

Optional entity filters

Narrow the page after you pick a grain:

Parameter	Use
`entity_type`	One canonical type, for example `reservation` or `consent`
`entity_id`	Source entity ID for that type

These filters still require guest_profile_id or master_profile_id when you want one guest.

What a row contains

Each event is a GuestEventLogEntry:

Field	Meaning
`id`	Casa Layer event ID
`property_id`	Property that observed the change
`integration_id`	Source mapping that produced the change
`guest_profile_id`	Sub-profile this change belongs to. Can be `null`.
`entity_type`	Changed entity, for example `guest_profile` or `reservation`
`entity_id`	Source entity ID the delta applies to
`delta`	Changed fields for that entity type
`observed_at`	When the source observed the change
`created_at`	When Casa Layer stored the row

entity_type values include guest_profile, reservation, transaction, action, loyalty_program, membership, review, channel, space, consent, and consent_retract.

{
  "mode": "timeline",
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "property_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "integration_id": "1f2d6c4e-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
      "guest_profile_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "entity_type": "guest_profile",
      "entity_id": "mews-guest-8842",
      "delta": { "first_name": "Ada" },
      "observed_at": "2026-03-01T10:15:00Z",
      "created_at": "2026-03-01T10:15:02Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

On Path B, rows can show different guest_profile_id values. Each value is one clustered member.

If the lookup is empty

Work through this list:

Confirm integration_id matches that PMS and property.
Confirm the PMS ID is the source_id Casa Layer ingested.
Confirm ingest has finished for that guest.
Remove X-Property-Id and try the group-wide guest lookup.
If the guest list is empty, resolve the guest from a reservation.
For Path B, confirm master_profile_id is not null.
For Path B, confirm the guest is clustered. Unclustered guests need Path A.

A source_id miss on GET /v1/guests is not 404. The list is empty. An event filter that matches nothing is also an empty list, not 404.

Errors

Status	Body	Meaning
`400`	`source_id requires integration_id`	You sent `source_id` without `integration_id`.
`400`	`invalid_cursor`	The `cursor` is malformed. Start from the first page.
`401`	`unauthorized`	Missing, unknown, or expired token.
`403`	`forbidden`	Missing scope, or `X-Property-Id` outside the group.

Partner API credentials

Create, rotate, and revoke the credential.

Data model

Guest event log grain and modes.

Guest event log

GET /v1/events reference.

Search by PMS identifiers

Resolve a guest or master from a PMS ID.

Get started

Concepts

Authentication

Use cases

AI

Retrieving the guest event log for a guest

What you need

1. Create partner credentials

2. Get an access token

3. Get property context

4. Get integration IDs

5. Resolve the guest from the PMS source ID

6. Read the event log

Path A — guest profile (one source system)

Path B — master profile (resolved guest)

Modes

Optional entity filters

What a row contains

If the lookup is empty

Errors

Partner API credentials

Data model

Guest event log

Search by PMS identifiers

​What you need

​1. Create partner credentials

​2. Get an access token

​3. Get property context

​4. Get integration IDs

​5. Resolve the guest from the PMS source ID

​6. Read the event log

​Path A — guest profile (one source system)

​Path B — master profile (resolved guest)

​Modes

​Optional entity filters

​What a row contains

​If the lookup is empty

​Errors

​Related

Partner API credentials

Data model

Guest event log

Search by PMS identifiers

What you need

1. Create partner credentials

2. Get an access token

3. Get property context

4. Get integration IDs

5. Resolve the guest from the PMS source ID

6. Read the event log

Path A — guest profile (one source system)

Path B — master profile (resolved guest)

Modes

Optional entity filters

What a row contains

If the lookup is empty

Errors

Related