> ## Documentation Index
> Fetch the complete documentation index at: https://heybtw.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# set_registration_status

> Change a guest's registration status on a synced Luma or Splash event, on the platform and in heyBTW's record together.

> [!WARNING]
>
> Writes to your event platform and to your heyBTW workspace on `action: "confirm"`: it changes the registration status of guests already on a synced Luma or Splash event, the same change the heyBTW dashboard makes. A preview changes nothing. It never adds a guest. heyBTW sends nothing to a guest, but the event platform may notify a guest of a change, per its own event settings.

Reach for it when the user wants to approve, decline or otherwise change a guest's status on an event synced to its platform. For an event that is not synced, [record\_signups](https://heybtw.com/docs/tools/record-signups.md) changes the status in heyBTW's record.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Approve Maya Chen and Sam Ortiz for the SF dinner."
* "Diego can't make it. Decline him on Luma."
* "Move the three people on the waitlist to approved."

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `channel_id` | string | Yes | One of your collabs, from [list\_events](https://heybtw.com/docs/tools/list-events.md). |
| `action` | string | Yes | `preview` or `confirm`. |
| `status` | string | Yes | One of `APPROVED`, `REGISTERED`, `DECLINED`, `WAITLIST`, `INVITED` or `PENDING_APPROVAL`, the statuses the dashboard's Status control offers. Check-in is not a registration status and is not set here. |
| `guests` | object\[] | Yes | Up to 100 people already on the collab's roster, each as `{"email": ...}`, `{"linkedin_url": ...}` or `{"name": ...}`. The first non-blank of the three is used. |
| `preview_token` | string | On confirm | From the preview, valid 15 minutes. |
| `client_request_id` | string | On confirm | A fresh hyphenated UUID for each new write. Reuse it only to retry that same write. |
| `contract_version` | string | No | Omit for v1, the only version advertised. |

## Workflow

**1. Preview**

`action: "preview"` with the `channel_id`, `status` and `guests`. Nothing changes. `data[0].guests` answers per guest, in the order named: the roster person matched, `current_status`, `requested_status`, `platform_value` (what the platform receives, or null when the platform does not take that status and only heyBTW's record changes) and the outcome a confirm would have. `data[0].outcome_facts` says what each outcome means. The preview carries a `preview_token` when at least one guest would change.

**2. Show the preview to the user**

Name each guest, the current and requested status, and what reaches the platform. Wait for the user's yes. A yes given before the preview does not count.

**3. Confirm**

`action: "confirm"` with the SAME `channel_id`, `status` and `guests`, that `preview_token` and a fresh `client_request_id`. Per guest the platform is changed first, and heyBTW's record only after the platform accepts.

A confirm whose guests moved since the preview, or whose preview expired or was already confirmed, is refused: preview again.

## Outcomes

| Outcome | Phase | Meaning |
| - | - | - |
| `will_change` | preview | A confirm would change this guest. |
| `unchanged` | both | The guest already has that status. |
| `not_on_roster` | both | No one on the roster matches. Nothing is created. |
| `ambiguous` | both | More than one person on the roster matches. Ask the user for the email. |
| `not_on_platform_guest_list` | both | On heyBTW's roster but not from the platform's own guest list. The platform is not called. |
| `decided_by_votes` | both | Partner votes decide this guest's status. Only the dashboard override changes it. |
| `changed` | confirm | The platform and heyBTW's record both changed. |
| `refused_by_platform` | confirm | The platform refused, with its own `platform_reason`. heyBTW's record is unchanged. |
| `platform_outcome_unknown` | confirm | Whether the platform applied it is not known. heyBTW's record is unchanged. The event platform shows whether it applied. |
| `changed_on_platform_only` | confirm | The platform accepted and heyBTW's record could not be written. |
| `not_attempted` | confirm | The confirm's time ran out before this guest. No call was made and nothing changed. |

Never report a refused or unknown guest as changed.

## Retry safely

On a transport error, retry the confirm with the SAME `client_request_id`. A confirm that ran is replayed (`idempotent_replay: true`), never repeated.

## Errors

* `invalid_parameter`: the collab has no event platform, is a Zuddl collab or is archived (the error says which), or the status is not one listed above (the error names the accepted ones). Nothing changes.
* `entity_not_found`: a partner's collab, the demo collab or an unknown id.
* `insufficient_scope`: the sign-in lacks write access. Nothing changes. Reconnect and approve write access on the consent screen.
* `rate_limit_exceeded`: wait for `Retry-After`. See [Limits and errors](https://heybtw.com/docs/mcp/limits-and-errors.md).

One collab and at most 100 guests per call. Writing needs no plan: every workspace can write.

## Related

* [record\_signups](https://heybtw.com/docs/tools/record-signups.md): sign-ups and statuses on an event with no platform sync.
* [get\_event\_details](https://heybtw.com/docs/tools/get-event-details.md): read the roster back.
* [Connect your CRM and event platform](https://heybtw.com/docs/playbooks/connect-crm-and-event-platform.md): syncing Luma, Splash or Zuddl.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.