Casa Layer · Every guest, remembered.

A partner often has only a PMS identifier. Casa Layer stores that value as source_id on the guest profile or the reservation. This guide shows how to find the master profile — the golden record for that guest. 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 profiles and master profiles
`read:reservations`	Reservation search by PMS reservation ID

You also need one of these from the PMS:

The guest profile ID (source_id on GET /v1/guests)
The reservation ID (source_id on GET /v1/reservations)

Some source systems do not expose a stable guest source_id. If the guest lookup returns no rows, use the reservation path.

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:reservations.
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. You can send X-Property-Id here too. The list then includes only mappings for that property.

GET /v1/guests and GET /v1/reservations reject source_id without integration_id. The error is 400.

5. Find the master profile

Use one of the paths below.

Path A — PMS guest profile ID

Call this when the PMS gives you a stable guest 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 master_profile_id. Then get the master profile. If data is empty, that PMS may not store a guest source_id. Use Path B. If master_profile_id is null, identity resolution has not merged this guest yet. You still have the guest profile. You do not have a master yet.

Path B — PMS reservation ID

Call this when you have the PMS reservation ID. This path also works when the PMS has no guest source_id. Search reservations with the same integration_id:

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

Read two IDs from the reservation row:

Field	What it is
`id`	Casa Layer reservation ID (UUID)
`guest_profile_id`	Casa Layer guest profile ID (UUID)
`source_id`	PMS reservation ID you sent

GET /v1/master-profiles accepts reservation_id. That parameter is the Casa Layer reservation ID, not the PMS source_id.

curl "https://api.casa-layer.com/v1/master-profiles?reservation_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The result includes member sub-profiles. If you only need one master, take the first row’s id. You can also load the guest, then read master_profile_id:

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

Get the master profile

Use the Casa Layer master profile ID from Path A or Path B.

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

The body is the golden record: canonical name and contact fields, attribute_sources, guest_profile_ids, and guest_profiles. See Master profiles and the API reference.

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, not a display number.
Confirm ingest has finished for that guest or reservation.
Remove X-Property-Id and try the group-wide call.
For a guest ID, switch to the reservation path.

Errors

Status	Body	Meaning
`400`	`source_id requires integration_id`	You sent `source_id` without `integration_id`.
`401`	`unauthorized`	Missing, unknown, or expired token.
`403`	`forbidden`	Missing scope, or `X-Property-Id` outside the group.
`404`	`not_found`	No master (or guest) with that Casa Layer ID.

A source_id miss on a list endpoint is not 404. The list is empty.

Partner API credentials

Create, rotate, and revoke the credential.

Data model

Guest profiles, master profiles, and reservations.

List integrations

Public roster of integration_id values.

Search master profiles

Search by email or Casa Layer reservation ID.

Guest event log

Read the event log for a guest or master from a PMS source ID.

Get started

Concepts

Authentication

Use cases

AI

Searching for a master profile using PMS identifiers

What you need

1. Create partner credentials

2. Get an access token

3. Get property context

4. Get integration IDs

5. Find the master profile

Path A — PMS guest profile ID

Path B — PMS reservation ID

Get the master profile

If the lookup is empty

Errors

Partner API credentials

Data model

List integrations

Search master profiles

Guest event log

​What you need

​1. Create partner credentials

​2. Get an access token

​3. Get property context

​4. Get integration IDs

​5. Find the master profile

​Path A — PMS guest profile ID

​Path B — PMS reservation ID

​Get the master profile

​If the lookup is empty

​Errors

​Related

Partner API credentials

Data model

List integrations

Search master profiles

Guest event log

What you need

1. Create partner credentials

2. Get an access token

3. Get property context

4. Get integration IDs

5. Find the master profile

Path A — PMS guest profile ID

Path B — PMS reservation ID

Get the master profile

If the lookup is empty

Errors

Related