# 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="<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>" 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="<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>" 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="<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>" 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](https://docs.ventrata.com/octo-core/bookings#endpoints), [Multi-Booking Cart](https://docs.ventrata.com/capabilities/cart), and [Gift Vouchers](https://docs.ventrata.com/gift-vouchers#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](https://docs.ventrata.com/online-check-in#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"
}
```