# Identities

To use this capability, add `octo/identities` to your `Octo-Capabilities` header.

{% hint style="warning" %}
`octo/identities` is currently an internal capability (`internal: true`) in the API source.
{% endhint %}

All paths below are public `/octo` routes.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/identities" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/identities/{identityId}" method="patch" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/identities/{identityId}" method="delete" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

`200 OK` with empty body.

## Attach Identity to Orders, Bookings, and Gifts

With this capability enabled, you can include `identityId` in any booking/order/gift payload handled by the create/update flows.

Order routes:

* `POST /orders`
* `PATCH /orders/{orderId}`
* `PATCH /orders/{orderId}/preview`
* `POST /orders/{orderId}/confirm`

Booking routes:

* `POST /bookings`
* `PATCH /bookings/{uuid}`
* `POST /bookings/{uuid}/confirm`

Gift routes:

* `POST /gifts`
* `PATCH /gifts/{uuid}`
* `PATCH /gifts/{uuid}/preview`
* `POST /gifts/{uuid}/confirm`

Base schemas: [Bookings](/octo-core/bookings.md#endpoints), [Multi-Booking Cart](/capabilities/cart.md), and [Gift Vouchers](/capabilities/gift-vouchers.md#endpoints).

When creating or updating an order with nested `bookings` and `gifts` arrays, each nested item can also include its own `identityId`.

## Check-in Lookup With Identity

When used with `octo/checkin`, check-in lookup can match bookings by identity.

This capability extends `POST /checkin/lookup` from [Online Check-in](/capabilities/online-check-in.md#lookup) with an identity filter.

### Request Body Additions

If `identityId` is not provided, check-in lookup behavior falls back to the standard `octo/checkin` lookup inputs.

## Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

### `Booking`

```json
{
  "// ...rest of booking object": "...",
  "identityId": "identity_customer_001",
  "identity": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "key": "loyalty_number"
  }
}
```

### `BookingWriteRequest`

```json
{
  "// ...rest of booking write request object": "...",
  "identityId": "identity_customer_001"
}
```

### `Gift`

```json
{
  "// ...rest of gift object": "...",
  "identityId": "identity_customer_001",
  "identity": {
    "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
    "key": "loyalty_number"
  }
}
```

### `GiftCreateRequest`

```json
{
  "// ...rest of gift create request object": "...",
  "identityId": "identity_customer_001"
}
```

### `Order`

```json
{
  "// ...rest of order object": "...",
  "identityId": "identity_customer_001",
  "identity": {
    "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "key": "loyalty_number"
  }
}
```

### `OrderCreateRequest`

```json
{
  "// ...rest of order create request object": "...",
  "identityId": "identity_customer_001"
}
```

### `OrderUpdateRequest`

```json
{
  "// ...rest of order update request object": "...",
  "identityId": "identity_customer_001"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ventrata.com/capabilities/identities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.