Identities

Link external customer identities to orders, bookings, and gifts

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

octo/identities is currently an internal capability (internal: true) in the API source.

All paths below are public /octo routes.

Create Identity

post

Creates a new identity.

Body

From capability octo/identities.

keystring · nullableOptional

Key value.

Example: loyalty_number

Responses

200

Returns an Identity object.

application/json

From capability octo/identities.

idstring · uuidRequired

Unique identifier for this resource.

Example: 3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7

identityIdstringOptional

Identity identifier.

Example: identity_customer_001

keystring · nullableOptional

Key value.

Example: loyalty_number

post/identities

POST /octo/identities HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "key": "loyalty_number"
}

200

Returns an Identity object.

{
  "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
  "identityId": "identity_customer_001",
  "key": "loyalty_number"
}

Update Identity

patch

Updates an existing identity.

Path parameters

identityIdstringRequired

Identity ID.

Example: identity_customer_001

Body

From capability octo/identities.

keystring · nullableOptional

Key value.

Example: loyalty_number

Responses

200

Returns an Identity object.

application/json

From capability octo/identities.

idstring · uuidRequired

Unique identifier for this resource.

Example: 3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7

identityIdstringOptional

Identity identifier.

Example: identity_customer_001

keystring · nullableOptional

Key value.

Example: loyalty_number

patch/identities/{identityId}

PATCH /octo/identities/{identityId} HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "key": "loyalty_number"
}

200

Returns an Identity object.

{
  "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
  "identityId": "identity_customer_001",
  "key": "loyalty_number"
}

Delete Identity

delete

Deletes an identity.

Path parameters

identityIdstringRequired

Identity ID.

Example: identity_customer_001

Responses

200

OK. No response body.

application/json

successbooleanRequired

Whether success is enabled.

Example: true

messagestringOptional

Message value.

Example: Deleted successfully.

delete/identities/{identityId}

DELETE /octo/identities/{identityId} HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

OK. No response body.

{
  "success": true,
  "message": "Deleted successfully."
}

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, Multi-Booking Cart, and Gift Vouchers.

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 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

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

BookingWriteRequest

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

Gift

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

GiftCreateRequest

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

Order

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

OrderCreateRequest

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

OrderUpdateRequest

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