Understory API (0.1.0)

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

This is an early version of the Bookings API specification.

The API is available in production for testing. Breaking changes might be introduced, but the overall specification is close to stable.

Operations

Get BookingsAlpha

Request

Get all bookings.

Security
OAuth2
Query
cursorstring

The cursor for pagination. An empty string indicates the start of the list.

limitinteger(int32)

The maximum number of bookings to return.

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&from=2019-08-24T14%3A15%3A22Z&limit=100&sort=-created_at&to=2019-08-24T14%3A15%3A22Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

The cursor for the next page. An empty string indicates the end of the list.

itemsArray of objects(Booking)
idstringrequired

The unique identifier of the booking.

statusstring(BookingStatus)required

The status of the booking.

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

For private customers, this is always "PRIVATE"

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)

Internal note for the booking.

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

The customer making the booking.

One of:

The customer making the booking.

customer_typestring(CustomerType)required

For company customers, this is always "COMPANY"

Enum"PRIVATE""COMPANY"
company_namestringrequired

The name of the company.

vat_numberstringrequired

The VAT number of the company.

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.

namestring

The name of the customer.

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

The status of the booking.

This will always be "ACTIVE" when the booking is created.

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

The status of the booking.

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

For private customers, this is always "PRIVATE"

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)

Internal note for the booking.

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": [
    { … }
  ]
}

Event

This is a preview of the Events API specification.

The API is not yet available in production.

Operations

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations

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