API docs by Redocly

TicketValidation Integration API (v1)

Download OpenAPI specification:

Public machine-to-machine API for TicketValidation integrations.

Getting started

  1. Sign in to TicketValidation dashboard as Admin.
  2. Go to Settings -> API Keys.
  3. Create a new API key:
    • Set a human-readable name (unique inside your customer account)
    • Choose one or more scopes (least privilege is recommended)
    • Optionally set expires_at
  4. Copy the generated key immediately (it is returned only once).
  5. Use it against https://api.ticketvalidation.com/integrations/v1/...

Authentication

Send one of the following headers:

  • X-API-Key: tvk_xxx
  • Authorization: ApiKey tvk_xxx

Scope model

Every endpoint in this API requires a matching scope. If scope is missing, API returns 403 with message API_KEY_SCOPE_DENIED.

Auth

API key identity and scope introspection.

Get authenticated API key context

Returns key metadata, customer id and granted scopes.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Locations

CRUD operations over customer locations.

List locations

Required scope: locations:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create location

Required scope: locations:manage.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
name
required
string <= 255 characters
responsible_person
required
string <= 255 characters
phone
required
string <= 255 characters
street_name
required
string <= 255 characters
street_number
string or null <= 50 characters
city
required
string <= 255 characters
country
required
string <= 255 characters
timezone
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "City Venue",
  • "responsible_person": "Operations Manager",
  • "phone": "+35315551234",
  • "street_name": "Grand Canal Street",
  • "street_number": "25",
  • "city": "Dublin",
  • "country": "Ireland",
  • "timezone": "Europe/Dublin"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "responsible_person": "string",
  • "phone": "string",
  • "street_name": "string",
  • "street_number": "string",
  • "city": "string",
  • "country": "string",
  • "timezone": "Europe/Dublin",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get location

Required scope: locations:read.

Authorizations:
ApiKeyHeader
path Parameters
locationId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "responsible_person": "string",
  • "phone": "string",
  • "street_name": "string",
  • "street_number": "string",
  • "city": "string",
  • "country": "string",
  • "timezone": "Europe/Dublin",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace location

Required scope: locations:manage.

Authorizations:
ApiKeyHeader
path Parameters
locationId
required
string
Request Body schema: application/json
required
name
string <= 255 characters
responsible_person
string <= 255 characters
phone
string <= 255 characters
street_name
string <= 255 characters
street_number
string or null <= 50 characters
city
string <= 255 characters
country
string <= 255 characters
timezone
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "responsible_person": "string",
  • "phone": "string",
  • "street_name": "string",
  • "street_number": "string",
  • "city": "string",
  • "country": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "responsible_person": "string",
  • "phone": "string",
  • "street_name": "string",
  • "street_number": "string",
  • "city": "string",
  • "country": "string",
  • "timezone": "Europe/Dublin",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete location

Required scope: locations:manage.

Authorizations:
ApiKeyHeader
path Parameters
locationId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Location deleted successfully"
}

Ticket Types

CRUD operations over ticket types.

List ticket types

Required scope: ticket-types:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create ticket type

Required scope: ticket-types:manage.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
name
required
string <= 255 characters
color
required
string^#[0-9A-Fa-f]{6}$
source_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "VIP",
  • "color": "#22AAFF",
  • "source_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "color": "string",
  • "sources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get ticket type

Required scope: ticket-types:read.

Authorizations:
ApiKeyHeader
path Parameters
ticketTypeId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "color": "string",
  • "sources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace ticket type

Required scope: ticket-types:manage.

Authorizations:
ApiKeyHeader
path Parameters
ticketTypeId
required
string
Request Body schema: application/json
required
name
string <= 255 characters
color
string^#[0-9A-Fa-f]{6}$
source_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": "string",
  • "source_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "color": "string",
  • "sources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete ticket type

Required scope: ticket-types:manage.

Authorizations:
ApiKeyHeader
path Parameters
ticketTypeId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Ticket type deleted successfully"
}

Ticket Sources

CRUD operations over ticket sources.

List ticket sources

Required scope: ticket-sources:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create ticket source

Required scope: ticket-sources:manage.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
name
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get ticket source

Required scope: ticket-sources:read.

Authorizations:
ApiKeyHeader
path Parameters
ticketSourceId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace ticket source

Required scope: ticket-sources:manage.

Authorizations:
ApiKeyHeader
path Parameters
ticketSourceId
required
string
Request Body schema: application/json
required
name
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete ticket source

Required scope: ticket-sources:manage.

Authorizations:
ApiKeyHeader
path Parameters
ticketSourceId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Ticket source deleted successfully"
}

Users

Read-only user discovery for integrations. User type values:

  • 1 -> Administrator
  • 2 -> Validator

List users

Required scope: users:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get user

Required scope: users:read.

Authorizations:
ApiKeyHeader
path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "type": 1,
  • "customer_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Events

CRUD operations over events and event dates.

List events

Required scope: events:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create event

Required scope: events:manage.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
name
required
string <= 255 characters
location_id
required
string
description
string or null
offline_validation_enabled
boolean or null
ticket_type_ids
Array of strings
required
Array of objects (EventValidator) non-empty
required
Array of objects (EventDateWrite) non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "location_id": "string",
  • "description": "string",
  • "offline_validation_enabled": true,
  • "ticket_type_ids": [
    ],
  • "validators": [
    ],
  • "dates": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "location_id": "string",
  • "description": "string",
  • "dates": [
    ],
  • "ticket_type_ids": [
    ],
  • "user_ids": [
    ],
  • "validators": [
    ],
  • "offline_validation_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get event

Required scope: events:read.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "location_id": "string",
  • "description": "string",
  • "dates": [
    ],
  • "ticket_type_ids": [
    ],
  • "user_ids": [
    ],
  • "validators": [
    ],
  • "offline_validation_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace event

Required scope: events:manage.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string
Request Body schema: application/json
required
name
string <= 255 characters
location_id
string
description
string or null
offline_validation_enabled
boolean or null
ticket_type_ids
Array of strings
required
Array of objects (EventValidator) non-empty
Array of objects (EventDateWrite)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "location_id": "string",
  • "description": "string",
  • "offline_validation_enabled": true,
  • "ticket_type_ids": [
    ],
  • "validators": [
    ],
  • "dates": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "location_id": "string",
  • "description": "string",
  • "dates": [
    ],
  • "ticket_type_ids": [
    ],
  • "user_ids": [
    ],
  • "validators": [
    ],
  • "offline_validation_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete event

Required scope: events:manage.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Event deleted successfully"
}

Tickets

Ticket listing, updates, imports and bulk operations.

List tickets for event with filters

Required scope: tickets:read.

Authorizations:
ApiKeyHeader
query Parameters
event_id
required
string
status
string
Enum: "validated" "not_validated"
ticket_type_id
string
ticket_source_id
string
import_id
string
search
string <= 255 characters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Insert ticket

Required scope: tickets:manage. You can pass multiple event_date_ids to fan out one ticket payload across multiple event days. The API creates one ticket record per provided event date, reusing the same ticket_id, type, source, and holder/email fields.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
event_id
required
string
event_date_ids
required
Array of strings non-empty
ticket_id
required
string <= 255 characters
ticket_type_id
required
string
ticket_source_id
required
string
holder
string or null <= 255 characters
email
string or null <email> <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JTK6S5Q6Q1X7XSRD4G9VQKAX",
  • "event_date_ids": [
    ],
  • "ticket_id": "VIP-1001",
  • "ticket_type_id": "01JTK6T74XKXBYM8D6RRETYJAZ",
  • "ticket_source_id": "01JTK6TF8EZ4CB77TY6Q5X4TN9",
  • "holder": "Alex Morgan",
  • "email": "john@example.com"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "Ticket inserted successfully"
}

Bulk insert tickets

Required scope: tickets:manage. Send multiple ticket payloads in tickets, and multiple event_date_ids when needed. The API creates one ticket record for each (ticket, event_date_id) combination. Example: 10 tickets x 3 event dates = 30 inserted ticket rows.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
event_id
required
string
event_date_ids
required
Array of strings non-empty
required
Array of objects (TicketWrite) non-empty

Responses

Request samples

Content type
application/json
{
  • "event_id": "01JTK6S5Q6Q1X7XSRD4G9VQKAX",
  • "event_date_ids": [
    ],
  • "tickets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "Tickets inserted successfully"
}

Replace ticket

Required scope: tickets:manage.

Authorizations:
ApiKeyHeader
path Parameters
ticketId
required
string
Request Body schema: application/json
required
ticket_id
string <= 255 characters
event_id
string
ticket_type_id
string
ticket_source_id
string or null
holder
string or null <= 255 characters
email
string or null <email> <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "ticket_id": "string",
  • "event_id": "string",
  • "ticket_type_id": "string",
  • "ticket_source_id": "string",
  • "holder": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer_id": "string",
  • "ticket_id": "string",
  • "event_id": "string",
  • "event_date_id": "string",
  • "ticket_type_id": "string",
  • "ticket_source_id": "string",
  • "import_id": "string",
  • "holder": "string",
  • "email": "user@example.com",
  • "validated_at": "2019-08-24T14:15:22Z",
  • "validated_by": "string",
  • "is_validated": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Bulk delete tickets by ticket record IDs for event

Required scope: tickets:manage. Send ticket record id values (ULIDs), not ticket_id business codes.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string
Request Body schema: application/json
required
ticket_ids
required
Array of strings [ 1 .. 1000 ] items [ items <= 255 characters ]

Ticket record IDs (ULIDs).

Responses

Request samples

Content type
application/json
{
  • "ticket_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Tickets deleted successfully"
}

Import tickets and create import record

Required scope: tickets:import.

Authorizations:
ApiKeyHeader
Request Body schema: application/json
required
event_id
required
string
event_date_ids
required
Array of strings non-empty
file_name
required
string <= 255 characters
required
Array of objects (TicketWrite) non-empty

Responses

Request samples

Content type
application/json
{
  • "event_id": "string",
  • "event_date_ids": [
    ],
  • "file_name": "string",
  • "tickets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "string"
}

List imports by event

Required scope: tickets:read.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete import and associated tickets

Required scope: tickets:import.

Authorizations:
ApiKeyHeader
path Parameters
eventId
required
string
importId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Import and associated tickets deleted successfully"
}

Billing

Current plan usage and ticket metrics.

Get billing usage snapshot

Required scope: billing:read.

Authorizations:
ApiKeyHeader

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}