> For the complete documentation index, see [llms.txt](https://chekin.gitbook.io/chekin-public-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chekin.gitbook.io/chekin-public-api/api-reference/guests/guest-schema-v2.md).

# Guest Schema v2

The "Guest Schema v2" endpoint returns the **complete guest form of a reservation in one response**: the default fields, the fields and agreement clauses added through a **Custom form** in the Chekin dashboard, and the Identity Verification settings.

It is the right choice when the properties you integrate use custom forms, or when you want to render the same form the Chekin guest app renders — groups, ordering, translations and all. If you only need the mandatory default fields, [Guest Schema](/chekin-public-api/api-reference/guests/guest-schema.md) is simpler; both versions are supported, and v1 is not deprecated.

{% hint style="info" %}
v2 follows the same iterative model as v1: the response depends on the values the guest has already provided, so re-request it whenever the guest changes one of the fields accepted in the request body. See the [Guest Schema](/chekin-public-api/api-reference/guests/guest-schema.md) page for the full description of each field.
{% endhint %}

## Endpoint

```
POST {{env}}/guests/schema/v2/
```

## Request and response in short

The request body is identical to [Guest Schema](/chekin-public-api/api-reference/guests/guest-schema.md): `reservation_id` is the only mandatory field, every other field is the current value of that field in your form. The response has three keys:

* **guest\_fields** — every field of the form, default **and** custom, whether it is currently active or not. Use `is_active` to decide what to render and `is_required` to decide what to enforce
* **agreement\_clauses** — the consent checkboxes configured in the custom form (terms, privacy policy, marketing…). Empty when the housing has no custom form
* **iv** — the Identity Verification settings of the reservation, same object as in [Guest Schema](/chekin-public-api/api-reference/guests/guest-schema.md), or `null` when the housing has no self online check-in enabled

{% hint style="warning" %}
Unlike v1, `guest_fields` is **not** filtered to the mandatory fields. A field with `is_active: false` must not be shown, and a field with `is_required: false` may be left empty. Always read both flags.
{% endhint %}

The full list of request fields and response attributes is in the reference block at the bottom of this page.

## Submitting custom fields and clauses

Custom fields and agreement clauses are sent in the same [Create Guest](/chekin-public-api/api-reference/guests/create-guest.md) / [Update Guest](/chekin-public-api/api-reference/guests/update-guest.md) request as the default fields:

* a custom field is a top-level key named after its `name`
* a clause consent is a boolean key named `agreement_clause_<id>`, one per clause — send `false` explicitly when the guest leaves an optional clause unchecked

```javascript
POST {{env}}/guests/
Authorization: JWT <token>
Content-Type: application/json

{
  "reservation_id": "fd73497a14cc4c0da9951b9824321169",
  "name": "Olga",
  "surname": "Fernandez",
  "...": "...",
  "arrival_time": "18:30",
  "agreement_clause_2dd7a19446a1439498e37b631546dd4f": true
}
```

The accepted clauses are returned by [Retrieve Guests information](/chekin-public-api/api-reference/guests/retrieve-guests-information.md) under `agreement_clauses`; add `?consents=history` to get every consent event chronologically instead of the current state.

{% openapi src="/files/2YNWdcD7SWYAbJN2lC4R" path="/guests/schema/v2" method="post" %}
[Chekin-Chekin-1.0.0-resolved.json](https://3564732132-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfAJzL2tAGO9ZwOToBa0R%2Fuploads%2Fgit-blob-0641a0e07e27281f11fe82de446c7229bfe15c1e%2FChekin-Chekin-1.0.0-resolved.json?alt=media)
{% endopenapi %}

<details>

<summary>Good to know</summary>

* **Leader fields.** A field or clause with `is_leaders_field: true` is returned active and required only while no leader has been registered on the reservation, unless you send `is_leader` / `force_show_leaders_fields` explicitly
* **`is_active: false` has several causes** — the field was removed in the custom form, it is not applicable to the housing country or the guest nationality, or it only applies to the leader and one is already registered. Treat them all the same way: don't render it
* **`type` differs from v1.** v2 returns it uppercase (`TEXT`, `SELECT`, `DATEPICKER`…), and custom fields add `DATE`, `TIME` and `PHONE`. When a default field is also configured in the custom form, the default type wins because it can change with the conditions
* **Custom-field `options`** carry a `label_translations` map next to `label`/`value`; default-field options don't

</details>