External API | TicketOpus

Authentication

API keys are company scoped.

Each company creates API clients in Admin, then grants scopes for the integration. Send the key in X-TicketOpus-Api-Key or as a bearer token.

curl -H "X-TicketOpus-Api-Key: top_xxx" \
  https://www.ticketopus.com/api/external/v1/companies/art-and-craft-studio/items

Scopes

Grant the narrowest access the client needs.

summary:readCompany profile, locations, categories, and users.

availability:readItems, custom fields, rates, availability, crew, and pickup options.

bookings:readBooking list and detailed reservation records.

bookings:writeDry-run validation, booking creation, cancellation, and notes.

checkin:readConfigured check-in statuses.

checkin:writeBarcode-based booking or participant check-in.

crew:readStructured crew role directory.

pickup:readLodgings and availability-specific pickup choices.

distribution:readChannel listing feed with allocated capacity.

Reference

External API endpoints

Method	Path	Scope	Purpose
GET	`/companies/{company}`	`summary:read`	Company metadata, branding, capabilities, locations, and categories.
GET	`/companies/{company}/users`	`summary:read`	Active admin users visible to integrations.
GET	`/companies/{company}/items`	`availability:read`	Bookable items with rates, variants, program rules, and custom fields.
GET	`/companies/{company}/items/{item}`	`availability:read`	Single item by id or URL name.
GET	`/companies/{company}/items/{item}/custom-fields`	`availability:read`	Checkout question schema and priced options for one item.
GET	`/companies/{company}/availabilities`	`availability:read`	Date-range availability with status, capacity, holds, and price.
GET	`/companies/{company}/availabilities/{availabilityId}`	`availability:read`	Availability detail with rates, crew, fields, and pickup options.
POST	`/companies/{company}/availabilities/{availabilityId}/bookings/validate`	`bookings:write`	Dry-run a booking without writing records.
POST	`/companies/{company}/availabilities/{availabilityId}/bookings`	`bookings:write`	Create an externally sourced booking with idempotency support.
GET	`/companies/{company}/bookings`	`bookings:read`	Search booking records by date range and status.
GET	`/companies/{company}/bookings/{bookingId}`	`bookings:read`	Booking detail, participants, payments, answers, notes, and attribution.
DELETE	`/companies/{company}/bookings/{bookingId}`	`bookings:write`	Cancel a booking after policy evaluation.
GET	`/companies/{company}/bookings/{bookingId}/cancellation-preview`	`bookings:write`	Preview refund and cancellation rule outcome.
POST	`/companies/{company}/bookings/{bookingId}/notes`	`bookings:write`	Add an auditable partner note.
PUT	`/companies/{company}/checkin`	`checkin:write`	Check in a participant or booking by barcode, ticket, voucher, or external id.
GET	`/companies/{company}/checkin-statuses`	`checkin:read`	Company-specific check-in status choices.
GET	`/companies/{company}/roles`	`crew:read`	Crew role directory for staff scheduling integrations.
GET	`/companies/{company}/lodgings`	`pickup:read`	Lodging and hotel pickup directory.
GET	`/companies/{company}/availabilities/{availabilityId}/lodgings`	`pickup:read`	Pickup options allowed for a specific availability.
GET	`/companies/{company}/distribution-feed`	`distribution:read`	Reseller feed with channel listings and allocated capacity.

Workflow

Recommended booking flow

1Fetch item schema

Read item rates, variants, and custom fields.

2Search availability

Choose a bookable availability and pickup option.

3Validate

Dry-run quantity, custom answers, voucher, and lodging.

4Create

Post with an idempotency key, customer data, participants, and payment amount.

5Operate

Use booking detail, notes, check-in, and cancellation preview after confirmation.

Errors

HTTP status codes

400Validation failed, capacity changed, or booking operation was rejected.

401API key is missing or invalid.

403The key is valid but missing the required scope.

404Company, item, availability, booking, or barcode was not found.

429Rate limit exceeded. Retry after the returned Retry-After value.

Example

Create an external booking

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-TicketOpus-Api-Key: top_xxx" \
  https://www.ticketopus.com/api/external/v1/companies/art-and-craft-studio/availabilities/00000000-0000-0000-0000-000000000000/bookings \
  -d '{
    "customerName": "Avery Morgan",
    "customerEmail": "[email protected]",
    "requestedQuantity": 2,
    "idempotencyKey": "reseller-order-8437",
    "voucherNumber": "FH-12345",
    "externalId": "reseller-booking-8437",
    "amountPaid": 90.00,
    "customFieldAnswers": [
      { "customFieldId": "00000000-0000-0000-0000-000000000000", "value": "yes" }
    ],
    "participants": [
      { "name": "Avery Morgan", "customerTypeName": "Adult" },
      { "name": "Riley Morgan", "customerTypeName": "Adult" }
    ]
  }'