Skip to content

Understory API

This is the reference documentation for the Understory API. Here you can find detailed information about the API endpoints, request and response formats, and authentication methods.

For more general information, go to Documentation.

Preview

You’re exploring an early preview of the Understory API documentation. Take a look around and see what’s available.

Want to help us test and improve it? Share your feedback by clicking the chat icon in the bottom right. We’d love to hear your thoughts!

Download OpenAPI description
index.json
index.yaml
Overview
License
Apache 2.0
Languages
Servers
https://api.understory.io/

Booking

Bookings related endpoints.

OperationsWebhooks

Get BookingsAlpha

Request

Get all bookings.

Security
OAuth2
Query
cursorstring

Pagination cursor for fetching the next page of results. Omit or pass an empty string to start from the beginning of the list.

limitinteger(int32)[ 1 .. 100 ]

Maximum number of items to return per page. Defaults to 100, maximum 100.

Default 100
fromstring(date-time)

Filter bookings made after the provided timestamp.

tostring(date-time)

Filter bookings made before the provided timestamp.

sortstring

Field to define the sort order. To indicate sorting direction, fields may be prefixed with + (ascending) or - (descending).

Ensure to URL escape the value as + can otherwise be interpreted as a space.

Only fields created_at and updated_at are supported.

Default "-created_at"
curl -i -X GET \
  'https://api.understory.io/v1/bookings?cursor=string&limit=100&from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z&sort=-created_at' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

Cursor for the next page of results. An empty string or absent value indicates the end of the list.

itemsArray of objects(Booking)
idstringrequired

The unique identifier of the booking.

statusstring(BookingStatus)required
Enum"ACTIVE""CANCELLED""MOVED""PROCESSING""CHECKED_IN""UNKNOWN"
created_atstring(date-time)required

Timestamp of when the booking was created.

updated_atstring(date-time)required

Timestamp of when the booking was last updated.

company_idstringrequired

The ID of the company hosting the experience.

experience_idstringrequired

The unique identifier of the experience.

event_idstringrequired

The unique identifier of the event.

customeranyrequired

The customer that made the booking.

customer_typestring(CustomerType)required
Enum"PRIVATE""COMPANY"
Discriminator
full_namestringrequired

The name of the customer.

emailstring(email)required

The email address of the customer.

phonestringrequired

The phone number of the customer.

addressobject(Address)required
address_linesArray of strings[ 1 .. 2 ] itemsrequired

Address lines. The first line is the primary address line, e.g. street name and number. The second line is the secondary address line, e.g. apartment number.

citystringrequired

The city of the customer.

zip_codestringrequired

The postal code of the customer.

countrystring(iso-3166-1-alpha-2)required

The country of the customer.

regionstring

The region of the customer. This can be a state, province, or other administrative region.

localestringrequired

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

sourcestring

The source of the booking.

internal_notestring(MarkdownText)
metadataobject

Additional metadata for the booking.

This property lets you add custom data to the booking, e.g. your own booking reference. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
Response
application/json
{
  "next": "string",
  "items": [
    { … }
  ]
}

Create BookingAlpha

Request

Create a new booking for an event.

Security
OAuth2
Bodyapplication/jsonrequired
event_idstringrequired

The unique identifier of the event.

customerCompanyCustomer (object) or PrivateCustomer (object)required
One of:

The customer making the booking.

object CompanyCustomer Recursive
localestringrequired

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

itemsArray of objects(Item)non-emptyrequired
type_idstringrequired

The unique identifier of the item type.

item_typestringrequired

The type of item.

Enum"VARIANT""ADDON""UNKNOWN"
quantityinteger>= 1required

The quantity of the item.

metadataobject

Additional metadata for the booking.

This property lets you add custom data to the booking, e.g. your own booking reference. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
curl -i -X POST \
  https://api.understory.io/v1/bookings \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_id": "string",
    "customer": {
      "customer_type": "PRIVATE",
      "company_name": "string",
      "vat_number": "string",
      "email": "user@example.com",
      "name": "string",
      "phone": "string",
      "address": {
        "address_lines": [
          "string"
        ],
        "city": "string",
        "zip_code": "string",
        "region": "string",
        "country": "string"
      }
    },
    "locale": "string",
    "items": [
      {
        "type_id": "string",
        "item_type": "VARIANT",
        "quantity": 1
      }
    ],
    "metadata": {
      "property1": "string",
      "property2": "string"
    }
  }'

Responses

Booking successfully created.

Bodyapplication/json
idstringrequired

The unique identifier of the booking.

statusstring(BookingStatus)required
Enum"ACTIVE""CANCELLED""MOVED""PROCESSING""CHECKED_IN""UNKNOWN"
Response
application/json
{
  "id": "string",
  "status": "ACTIVE"
}

Get BookingAlpha

Request

Get a booking by its ID.

Security
OAuth2
Path
bookingIdstringrequired

The unique identifier of the booking.

curl -i -X GET \
  'https://api.understory.io/v1/bookings/{bookingId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier of the booking.

statusstring(BookingStatus)required
Enum"ACTIVE""CANCELLED""MOVED""PROCESSING""CHECKED_IN""UNKNOWN"
created_atstring(date-time)required

Timestamp of when the booking was created.

updated_atstring(date-time)required

Timestamp of when the booking was last updated.

company_idstringrequired

The ID of the company hosting the experience.

experience_idstringrequired

The unique identifier of the experience.

event_idstringrequired

The unique identifier of the event.

customeranyrequired

The customer that made the booking.

customer_typestring(CustomerType)required
Enum"PRIVATE""COMPANY"
Discriminator
full_namestringrequired

The name of the customer.

emailstring(email)required

The email address of the customer.

phonestringrequired

The phone number of the customer.

addressobject(Address)required
address_linesArray of strings[ 1 .. 2 ] itemsrequired

Address lines. The first line is the primary address line, e.g. street name and number. The second line is the secondary address line, e.g. apartment number.

citystringrequired

The city of the customer.

zip_codestringrequired

The postal code of the customer.

countrystring(iso-3166-1-alpha-2)required

The country of the customer.

regionstring

The region of the customer. This can be a state, province, or other administrative region.

localestringrequired

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

sourcestring

The source of the booking.

internal_notestring(MarkdownText)
metadataobject

Additional metadata for the booking.

This property lets you add custom data to the booking, e.g. your own booking reference. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
Response
application/json
{
  "id": "string",
  "status": "ACTIVE",
  "source": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "company_id": "string",
  "experience_id": "string",
  "event_id": "string",
  "locale": "string",
  "customer": {
    "customer_type": "PRIVATE",
    "company_name": "string",
    "vat_number": "string",
    "email": "user@example.com",
    "name": "string",
    "phone": "string",
    "address": { … }
  },
  "internal_note": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Get TicketsAlpha

Request

Get all tickets for a booking.

Security
OAuth2
Path
bookingIdstringrequired

The unique identifier of the booking.

curl -i -X GET \
  'https://api.understory.io/v1/bookings/{bookingId}/tickets' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
itemsArray of objects(Ticket)
idstringrequired

The unique identifier of the ticket.

urlsArray of objectsnon-emptyrequired

The URLs associated with the ticket.

typestringrequired

The type of the URL.

Value"PDF"
urlstring(uri)required

URL to the ticket.

statusstringrequired

The status of the ticket.

Enum"ACTIVE""VOIDED""CHECKED_IN""UNKNOWN"
itemsArray of objects(Item)required

The items associated with the ticket, e.g. variants or addons.

type_idstringrequired

The unique identifier of the item type.

item_typestringrequired

The type of item.

Enum"VARIANT""ADDON""UNKNOWN"
quantityinteger>= 1required

The quantity of the item.

check_inobject
check_in_timestring(date-time)required

Timestamp of when the ticket was checked in.

checked_in_bystringrequired

The ID of the person who checked in the ticket.

methodstringrequired

The method used to check in the ticket.

Enum"MANUAL""QR_CODE_SCAN""UNKNOWN"
Response
application/json
{
  "items": [
    { … }
  ]
}

Booking createdPreviewWebhook

Request

Sent when a new booking is created.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the created booking.

booking_idstringrequired

The unique identifier of the created booking.

host_idstringrequired

The unique identifier of the host (company) that owns the booking.

experience_idstringrequired

The unique identifier of the experience this booking is for.

event_idstringrequired

The unique identifier of the event this booking is for.

application/json
{
  "booking_id": "string",
  "host_id": "string",
  "experience_id": "string",
  "event_id": "string"
}

Responses

OK

Booking updatedPreviewWebhook

Request

Sent when a booking is updated.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the updated booking.

booking_idstringrequired

The unique identifier of the updated booking.

host_idstringrequired

The unique identifier of the host (company) that owns the booking.

experience_idstringrequired

The unique identifier of the experience this booking is for.

event_idstringrequired

The unique identifier of the event this booking is for.

application/json
{
  "booking_id": "string",
  "host_id": "string",
  "experience_id": "string",
  "event_id": "string"
}

Responses

OK

Booking cancelledPreviewWebhook

Request

Sent when a booking is cancelled.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the cancelled booking.

booking_idstringrequired

The unique identifier of the cancelled booking.

host_idstringrequired

The unique identifier of the host (company) that owns the booking.

event_idstringrequired

The unique identifier of the event this booking was for.

application/json
{
  "booking_id": "string",
  "host_id": "string",
  "event_id": "string"
}

Responses

OK

Event Availability

Query availability for events.

Event availability is a computed value based on a number of parameters, including:

  • Event capacity and current reservations
  • Resources linked to tickets and bookings (e.g., bikes, kayaks, equipment)
  • Booking cut-off time

The availability response includes both an overall availability status and a breakdown of individual constraints, allowing you to understand exactly what factors are limiting availability for a given event.

Operations

Event

This is a preview of the Events API specification.

The API is not yet available in production.

OperationsWebhooks

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

OperationsWebhooks

Grow

This is a collection of endpoints related to Understory Grow.

Operations

Test

These endpoints are for testing purposes only.

You can use them to verify that your integration authentication works as intended.

Operations

Webhook

Webhook subscription management and event delivery.

Webhooks are sent to subscriber endpoints when events occur related to experiences, events, and bookings.

OperationsWebhooks