> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casa-layer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Searching for a master profile using PMS identifiers
> Find a Casa Layer master profile from a PMS guest ID or reservation ID.
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](/partner-credentials). 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](/api-reference/list-integrations) |
| `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](/partner-credentials) for the full steps.
1. Open **Integrations → Partner credentials → Custom Integration**.
2. Name the credential.
3. Select `read:properties`, `read:guests`, and `read:reservations`.
4. Click **Create credentials**.
5. 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.
```bash theme={null}
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:
```bash theme={null}
-H "Authorization: Bearer $ACCESS_TOKEN"
```
## 3. Get property context
List the properties in the credential's group.
```bash theme={null}
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.
```bash theme={null}
-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.
```bash theme={null}
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.
```bash theme={null}
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.
```json theme={null}
{
"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](#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`:
```bash theme={null}
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`.
```bash theme={null}
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`:
```bash theme={null}
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.
```bash theme={null}
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](/data-model#master-profiles) and the
[API reference](/api-reference/get-a-master-profile).
## If the lookup is empty
Work through this list:
1. Confirm `integration_id` matches that PMS and property.
2. Confirm the PMS ID is the `source_id` Casa Layer ingested, not a display
number.
3. Confirm ingest has finished for that guest or reservation.
4. Remove `X-Property-Id` and try the group-wide call.
5. 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.
## Related
Create, rotate, and revoke the credential.
Guest profiles, master profiles, and reservations.
Public roster of `integration_id` values.
Search by email or Casa Layer reservation ID.
Read the event log for a guest or master from a PMS source ID.