Casa Layer · Every guest, remembered.

A table is a group-owned list of guests you keep for operations work. It is not a marketing segment. Campaign audiences live in a downstream ESP. Each table has a fixed grain and a type:

Field	Values	Meaning
`member_type`	`guest` or `master`	Guest profiles, or master profiles. Set at create. Never mixed.
`type`	`static` or `dynamic`	Hand-picked members, or members from a saved filter.

Use a dynamic table for this recipe. Save a filter on marketing_email_consent. Casa Layer then keeps members whose effective marketing-email status is granted. Partner credentials are read-only. An operator creates the table in the Casa Layer app. The partner then reads members over the public API.

What you need

An operator with access to the Casa Layer app creates and saves the table. The partner credential needs these scopes:

Scope	Why you need it
`read:tables`	Table list, detail, members, filters, preview, and runs
`read:consents`	Optional extra check on stored consent observations
`read:guests`	Optional load of a master and its member guests

write:tables is session-only. Partner credentials cannot create or save a table.

What a table is

A table holds members in one property group. Member rows are directory projections: name, email, phone, and when the member entered the table. Each member also returns:

Field	Meaning
`id`	Membership key
`guest_profile_id`	Casa Layer guest profile ID, or `null` on a clustered master
`master_profile_id`	Casa Layer master profile ID when one exists
`consents`	Effective status per `contact_method` and `purpose`
`kind`	`clustered` or `singleton` on a master table. Not the table `type`.

On a guest table, id and guest_profile_id are the same. Use guest_profile_id on other endpoints. On a master table:

A clustered row has master_profile_id set and guest_profile_id null. Load member guests from GET /v1/master-profiles/{id}.
A singleton row is an unclustered guest. guest_profile_id is set. master_profile_id is null.

consents is the effective rollup. When more than one observation exists for the same contact method and purpose, Casa Layer keeps the most restrictive status: withdrawn, then denied, then granted. No consent row means unknown. Unknown is not granted. A guest with an empty consents array has not provided marketing consent. See Tables and Consents.

1. Create the table in the app

Do this in the Casa Layer app. Do not call create from a partner credential.

Open Tables.
Click Create table.
Enter a name, for example Marketing email granted.
Set Type to Dynamic.
Set Guest profile type:
- Guest profiles — one row per source record
- Master profiles (default) — one row per resolved guest
Click Create table.

Type and guest profile type cannot change after create. For most partner reads, pick Guest profiles. Each member then has a guest_profile_id you can send to other endpoints. Pick Master profiles when the partner wants one row per real guest. The new table opens with no members. Add the filter, then save it.

Click Filter.
Set Field to Marketing email consent.
Set Condition to is.
Set Value to Granted.
Click Save.

Save writes the filter and refreshes membership. Wait until the run finishes. Then members are the current match set. The saved filter is this document:

{
  "version": 1,
  "root": {
    "op": "and",
    "children": [
      {
        "field": "marketing_email_consent",
        "operator": "is",
        "value": "granted"
      }
    ]
  }
}

marketing_email_consent is the effective marketing-email status for the member. Allowed values are granted, denied, and withdrawn. A static table does not apply this filter. If you add members by hand, validate consents on every row. Do not trust membership alone.

Tables are not marketing segments. A destination still needs its own consent check. Membership is an operations list, not a send licence.

3. 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:tables. Add read:consents and read:guests if the partner will run the extra checks below.
Click Create credentials.
Copy the client ID and client secret.

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

4. 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. Send the token as a bearer credential on every request below:

-H "Authorization: Bearer $ACCESS_TOKEN"

5. Find the table

curl "https://api.casa-layer.com/v1/tables?status=active" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Table list uses offset pages. Default limit is 100. The maximum is 500. Match the table by name, or store id when the operator creates it.

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

Confirm type is dynamic and member_type is the grain you chose. Read the saved filter:

curl https://api.casa-layer.com/v1/tables/3fa85f64-5717-4562-b3fc-2c963f66afa6/filters \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Confirm filter_doc includes marketing_email_consent with value granted. You can also preview a filter without a saved table:

curl -X POST https://api.casa-layer.com/v1/tables/preview \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member_type": "guest",
    "filter_doc": {
      "version": 1,
      "root": {
        "op": "and",
        "children": [
          {
            "field": "marketing_email_consent",
            "operator": "is",
            "value": "granted"
          }
        ]
      }
    }
  }'

The preview returns a count. It does not return members. Use it to check the filter before the operator saves.

6. Retrieve members

curl "https://api.casa-layer.com/v1/tables/3fa85f64-5717-4562-b3fc-2c963f66afa6/members?limit=100&offset=0" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Member list uses offset pages. When has_more is true, send offset equal to next_offset. Repeat until has_more is false.

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "guest_profile_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "master_profile_id": null,
      "first_name": "Ada",
      "surname": "Lovelace",
      "email_address": "[email protected]",
      "phone_number": null,
      "entered_at": "2026-03-01T10:15:02Z",
      "kind": null,
      "consents": [
        {
          "contact_method": "email",
          "purpose": "marketing",
          "status": "granted"
        }
      ]
    }
  ],
  "has_more": false,
  "next_offset": null
}

On a clustered master member the same page looks like this:

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "guest_profile_id": null,
  "master_profile_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "kind": "clustered",
  "consents": [
    {
      "contact_method": "email",
      "purpose": "marketing",
      "status": "granted"
    }
  ]
}

A property-pinned personal API key narrows visible members. Partner credentials are group-scoped. They see every member in the group. Treat each member as granted only when consents contains a row that matches all three fields:

Field	Required value
`purpose`	`marketing`
`contact_method`	`email`
`status`	`granted`

Reject the member when:

consents is missing or empty
the marketing-email row is denied or withdrawn
the only granted row is a different purpose or contact method

Email and SMS are separate. A granted SMS row is not email consent. On a clustered master, consents already rolls up member guests. You do not need a guest profile ID to validate that row.

Optional — load member guests of a clustered master

When guest_profile_id is null, load the master:

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

Read guest_profile_ids. Each value is a Casa Layer guest profile ID.

Optional — list stored observations

GET /v1/consents returns individual observations. It does not return the effective rollup. guest_profile_id on that route is ingest-time provenance only.

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

Use this to inspect source rows. Use member consents to decide eligibility. This search has no master_profile_id filter. For a clustered master, validate consents on the member, or call the search once per guest profile ID.

If the member list is empty

Work through this list:

Confirm the operator clicked Save after the filter.
Confirm GET /v1/tables/{id}/filters shows marketing_email_consent is granted.
Confirm ingest has stored consent observations.
Confirm you did not expect unknown guests. No row means unknown.
Confirm member_type matches the grain you want.
For a static table, add members by hand. The filter does not run.

Errors

Status	Body	Meaning
`401`	`unauthorized`	Missing, unknown, or expired token.
`403`	`forbidden`	Missing `read:tables`, or a write from a partner credential.
`404`	`not_found`	No table with that Casa Layer ID.

An empty member page is not 404. The list is empty.

Partner API credentials

Create, rotate, and revoke the credential.

Data model

Tables, members, and consents.

Browse table members

GET /v1/tables/{id}/members reference.

Search consents

Stored consent observations.

Get started

Concepts

Authentication

Use cases

AI

Creating a table of guests who have provided marketing consent

What you need

What a table is

1. Create the table in the app

3. Create partner credentials

4. Get an access token

5. Find the table

6. Retrieve members

Optional — load member guests of a clustered master

Optional — list stored observations

If the member list is empty

Errors

Partner API credentials

Data model

Browse table members

Search consents

​What you need

​What a table is

​1. Create the table in the app

​2. Save the marketing consent filter

​3. Create partner credentials

​4. Get an access token

​5. Find the table

​6. Retrieve members

​7. Validate marketing consent

​Optional — load member guests of a clustered master

​Optional — list stored observations

​If the member list is empty

​Errors

​Related

Partner API credentials

Data model

Browse table members

Search consents

What you need

What a table is

1. Create the table in the app

2. Save the marketing consent filter

3. Create partner credentials

4. Get an access token

5. Find the table

6. Retrieve members

7. Validate marketing consent

Optional — load member guests of a clustered master

Optional — list stored observations

If the member list is empty

Errors

Related