Management API

1. Overview

Version: 1.73.0

In the tables below, a name marked with ^* is required.

1.1. Seatmap.pro Management API v2

Enterprise administration API for managing organizational structure, user access, and tenant configurations. Restricted to super admin users with elevated privileges.

1.1.1. Core Capabilities

Organization Management

Create organizations - Establish new organizational entities with user credentials
Update organizations - Modify organizational details and settings
List organizations - Retrieve all organizations with pagination support
Delete organizations - Remove organizational entities and associated data
Access control - Manage API keys and authentication tokens

Administrative Features

User provisioning - Create initial admin users with organization setup
Token management - Generate and revoke organization Secret API keys
Multi-tenancy - Manage multiple organizations within tenant boundaries
Audit capabilities - Track organizational changes and access patterns

1.1.2. API Design

Response Formats

Success responses - JSON with organizational data and HTTP status codes
Error responses - RFC 7807 Problem Details with enhanced metadata (see Error Response Format section below)
Pagination - Standard page/size parameters for organization listings

Authentication

All endpoints require tenant-level authentication: [source]

X-API-Key: {tenantToken}

Tenant tokens are obtained from the Editor application login response and provide elevated super admin access. For detailed access management, see Managing Access.

1.1.3. Implementation Guidelines

Security Requirements

Restricted access - Only super admin users should access these endpoints
Token security - Store tenant tokens securely (encrypted at rest)
Audit logging - Log all management operations for compliance
Rate limiting - Implement exponential backoff for 429 responses

Best Practices

Error handling - Parse RFC 7807 error responses with field-level details
Validation - Pre-validate organization data before submission
Idempotency - Handle duplicate organization creation gracefully
Connection pooling - Reuse HTTP connections for multiple requests

Enhanced Error Response Format: All error responses follow RFC 7807 Problem Details format with additional metadata:

type - URI reference identifying the problem type (default: about:blank)
title - Human-readable summary of the error category
status - HTTP status code
detail - Human-readable explanation of the specific error
instance - URI reference of the specific occurrence
timestamp - ISO-8601 timestamp when the error occurred
path - Request path that triggered the error
errorCode - Machine-readable error category code
errors - Array of detailed field-level errors (for validation failures) Each error in the errors array contains:
field - Name of the field that failed validation
message - Human-readable error message
rejectedValue - The invalid value that was submitted (may be null)
code - Validation constraint code (e.g., NOT_NULL, SIZE)

2. Quick Start

2.1. Authentication

All API requests require authentication using API keys provided in HTTP headers.

2.1.1. API Key Authentication

Include your API key in the request header:

curl -X GET "https://api.seatmap.pro/api/private/v2.0/events" \
  -H "X-API-Key: your-api-key-here"

2.1.2. Organization Context

For tenant-level API keys, you must also provide the organization ID:

curl -X GET "https://api.seatmap.pro/api/private/v2.0/events" \
  -H "X-API-Key: your-tenant-api-key" \
  -H "X-Organization-ID: organization-uuid"

2.1.3. Token Management

Your API tokens can be obtained from the Editor application after login. For more information about managing access tokens, see the Managing Access Guide.

Keep your API keys secure and never commit them to version control.

2.2. Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

2.2.1. Status Codes

Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
204	No Content - Request successful, no response body
400	Bad Request - Validation error or malformed request
403	Forbidden - Unauthorized access or insufficient permissions
404	Not Found - Requested resource does not exist
409	Conflict - Data integrity violation or duplicate resource
500	Internal Server Error - Unexpected server error occurred

2.2.2. Error Response Format

Error responses follow RFC 7807 Problem Details, extended with timestamp, path, errorCode and an errors array of field-level details:

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 400,
  "detail": "Validation failed: 2 fields have errors",
  "instance": "/api/private/v2.0/events/123e4567-e89b-12d3-a456-426614174000/selection/",
  "timestamp": "2026-02-14T10:30:45.123Z",
  "path": "/api/private/v2.0/events/123e4567-e89b-12d3-a456-426614174000/selection/",
  "errorCode": "VALIDATION_FAILED",
  "errors": [
    {
      "field": "seats[0].seatId",
      "message": "Seat ID must not be null",
      "rejectedValue": null,
      "code": "NOT_NULL"
    },
    {
      "field": "seats[1].assignmentId",
      "message": "Assignment ID must not be null",
      "rejectedValue": null,
      "code": "NOT_NULL"
    }
  ]
}

Responses use the application/problem+json content type. There is no error member and no top-level message member: read detail for the summary and errors[].message for field-level messages.

2.2.3. Best Practices

Always check the HTTP status code before processing the response
Branch on errorCode rather than parsing detail, which is human-readable and may change
Implement retry logic for 500-series errors with exponential backoff
Log error responses for debugging
Handle validation errors (400) by reading the errors array

2.3. Pagination

List endpoints return paginated results to improve performance and reduce response size.

2.3.1. Pagination Parameters

Parameter	Type	Description
page	integer	Page number (zero-based). Default: 0
size	integer	Number of items per page. Default: 20, Max: 100
sort	string	Sort field and direction, e.g., "name,asc" or "createdDate,desc"

Parameter

Type

Description

page

integer

Page number (zero-based). Default: 0

size

integer

Number of items per page. Default: 20, Max: 100

sort

string

Sort field and direction, e.g., "name,asc" or "createdDate,desc"

2.3.2. Example Request

curl -X GET "https://api.seatmap.pro/api/private/v2.0/events?page=0&size=20&sort=name,asc" \
  -H "X-API-Key: your-api-key"

2.3.3. Response Structure

Paginated responses include metadata about the result set:

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Summer Concert 2026"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "sorted": true,
      "unsorted": false
    }
  },
  "totalElements": 150,
  "totalPages": 8,
  "last": false,
  "first": true,
  "number": 0,
  "size": 20
}

2.3.4. Navigating Pages

first: true if this is the first page
last: true if this is the last page
totalPages: total number of pages available
totalElements: total number of items across all pages
number: current page number (zero-based)

3. API Endpoints

Endpoints are organized by functional area. Each section includes detailed information about available operations.

3.1. Organizations

Organization administration endpoints restricted to super admin users. Manages organizational structure, authentication keys, and domain configurations. Requires elevated access privileges.

3.1.1. POST /api/private/management/v2.0/organizations/

Operation: addOrganization

Create a organization

Parameters

Body Parameter

Name

Description

Default

OrganizationWithUser^*

OrganizationWithUser

Return Type

Organization

Content Type

/
application/problem+json
application/json

Responses

Table 1. HTTP Response Codes
Code	Message	Datatype
201	Organization created successfully	Organization
400	Bad Request - Validation error or malformed request	ProblemDetail
403	Forbidden - Unauthorized access or insufficient permissions	ProblemDetail
500	Internal Server Error - Unexpected server error occurred	ProblemDetail
409	Conflict - Data integrity violation or duplicate resource	ProblemDetail

Request Content Type

application/json

Examples

Try this request in the API Explorer

HTTP Request

POST /api/private/management/v2.0/organizations/ HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
Content-Length: 427
Host: booking.seatmap.pro

{
  "id" : null,
  "name" : "Test Organization",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10,
  "lastName" : "New User",
  "firstName" : "New User",
  "password" : "c1065fed-9ff1-4c7f-a4ba-2a4ebce6450c",
  "email" : "newuser@test.com"
}

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/organizations/' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w' \
    -d '{
  "id" : null,
  "name" : "Test Organization",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10,
  "lastName" : "New User",
  "firstName" : "New User",
  "password" : "c1065fed-9ff1-4c7f-a4ba-2a4ebce6450c",
  "email" : "newuser@test.com"
}'

Response Body

{
  "id" : 2,
  "name" : "Test Organization",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}

3.1.2. DELETE /api/private/management/v2.0/organizations/{id}

Operation: deleteOrganizationById

Delete a organization

Parameters

Body Parameter

Name

Description

Default

Path Parameters

Name

Description

Default

id^*

null

Return Type

Content Type

application/problem+json
application/json

Responses

Table 2. HTTP Response Codes
Code	Message	Datatype
204	Successfully deleted	<<>>
400	Bad Request - Validation error or malformed request	ProblemDetail
403	Forbidden - Unauthorized access or insufficient permissions	ProblemDetail
404	Not Found - Requested resource does not exist	ProblemDetail
500	Internal Server Error - Unexpected server error occurred	ProblemDetail
409	Conflict - Data integrity violation or duplicate resource	ProblemDetail

Examples

Try this request in the API Explorer

HTTP Request

DELETE /api/private/management/v2.0/organizations/2 HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
Host: booking.seatmap.pro

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/organizations/2' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w'

Response Body

3.1.3. GET /api/private/management/v2.0/organizations/{id}

Operation: getOrganizationById

Retrieves a specific organization by id

Getting organization by Id

Parameters

Body Parameter

Name

Description

Default

Path Parameters

Name

Description

Default

id^*

null

Return Type

Organization

Content Type

/
application/problem+json
application/json

Responses

Table 3. HTTP Response Codes
Code	Message	Datatype
200	Returns the organization	Organization
400	Bad Request - Validation error or malformed request	ProblemDetail
403	Forbidden - Unauthorized access or insufficient permissions	ProblemDetail
404	Not Found - Requested resource does not exist	ProblemDetail
500	Internal Server Error - Unexpected server error occurred	ProblemDetail

Examples

Try this request in the API Explorer

HTTP Request

GET /api/private/management/v2.0/organizations/2 HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
Host: booking.seatmap.pro

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/organizations/2' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w'

Response Body

{
  "id" : 2,
  "name" : "Test Organization",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}

3.1.4. GET /api/private/management/v2.0/organizations/

Operation: getOrganizations

Retrieve list of all organizations

Getting all the organizations with paging

Parameters

Body Parameter

Name

Description

Default

Query Parameters

Name

Description

Default

page

Zero-based page index (0..N)

size

The size of the page to be returned

sort

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

null

Return Type

PageOrganization

Content Type

/
application/problem+json
application/json

Responses

Table 4. HTTP Response Codes
Code	Message	Datatype
200	Returns list of organizations	PageOrganization
400	Bad Request - Validation error or malformed request	ProblemDetail
403	Forbidden - Unauthorized access or insufficient permissions	ProblemDetail
500	Internal Server Error - Unexpected server error occurred	ProblemDetail

Examples

Try this request in the API Explorer

HTTP Request

GET /api/private/management/v2.0/organizations/ HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
Host: booking.seatmap.pro

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/organizations/' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w'

Response Body

{
  "content" : [ {
    "id" : 1,
    "name" : "test organization",
    "publicKey" : "bd780a2f-9b9d-48a8-ad05-34dc5154fb9a",
    "privateKey" : "af90387c-9071-4015-9a58-cbb543d84130",
    "domain" : null,
    "autologinEnabled" : false,
    "appendDomainToLogin" : false,
    "type" : "VENUE",
    "tenantId" : 10
  }, {
    "id" : 2,
    "name" : "Test Organization",
    "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
    "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
    "domain" : null,
    "autologinEnabled" : false,
    "appendDomainToLogin" : false,
    "type" : "DEFAULT",
    "tenantId" : 10
  } ],
  "pageable" : {
    "pageNumber" : 0,
    "pageSize" : 20,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "size" : 20,
  "number" : 0,
  "first" : true,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "numberOfElements" : 2,
  "empty" : false
}

3.1.5. PUT /api/private/management/v2.0/organizations/

Operation: updateOrganization

Update a organization

Parameters

Body Parameter

Name

Description

Default

Organization^*

Organization

Return Type

Organization

Content Type

/
application/problem+json
application/json

Responses

Table 5. HTTP Response Codes
Code	Message	Datatype
200	Organization updated successfully	Organization
400	Bad Request - Validation error or malformed request	ProblemDetail
403	Forbidden - Unauthorized access or insufficient permissions	ProblemDetail
404	Not Found - Requested resource does not exist	ProblemDetail
500	Internal Server Error - Unexpected server error occurred	ProblemDetail
409	Conflict - Data integrity violation or duplicate resource	ProblemDetail

Request Content Type

application/json

Examples

Try this request in the API Explorer

HTTP Request

PUT /api/private/management/v2.0/organizations/ HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
Content-Length: 272
Host: booking.seatmap.pro

{
  "id" : 2,
  "name" : "NEW_NAME",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : true,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/organizations/' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w' \
    -d '{
  "id" : 2,
  "name" : "NEW_NAME",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : true,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}'

Response Body

{
  "id" : 2,
  "name" : "NEW_NAME",
  "publicKey" : "facd6165-1d4a-4bfb-9162-8a0312deb2f0",
  "privateKey" : "6a3166c5-f2a0-43d4-bfdd-4f95c4a488ce",
  "domain" : null,
  "autologinEnabled" : true,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}

3.2. SessionConfig

3.2.1. PUT /api/private/management/v2.0/session-config/

Operation: updateSessionConfig

Update booking session configuration

Upserts the organization’s session configuration. Public session creation stays disabled until explicitly enabled here.

Parameters

Body Parameter

Name

Description

Default

SessionConfigDto^*

SessionConfigDto

Return Type

SessionConfigDto

Content Type

/
application/problem+json
application/json

Responses

Table 6. HTTP Response Codes
Code	Message	Datatype
200	OK	SessionConfigDto
409	Conflict - Data integrity violation or duplicate resource	ProblemDetail

Request Content Type

application/json

Examples

Try this request in the API Explorer

HTTP Request

PUT /api/private/management/v2.0/session-config/ HTTP/1.1
Content-Type: application/json
X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w
X-Organization-ID: 1
Content-Length: 36
Host: booking.seatmap.pro

{
  "publicSessionsEnabled" : true
}

cURL Request

$ curl 'https://booking.seatmap.pro/api/private/management/v2.0/session-config/' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'X-Api-Key: TEN:tLRTiAnxVKyJcunhg6hwMkU:fpmJqHgxYiNe-B6FNqg-w' \
    -H 'X-Organization-ID: 1' \
    -d '{
  "publicSessionsEnabled" : true
}'

Response Body

{
  "publicSessionsEnabled" : true
}

4. Data Models

This section describes all data structures used in the API.

4.1. ErrorDetail

Name

Type

Description

field

String

Name of the field that failed validation

message

String

Human-readable error message

rejectedValue

any

code

String

Validation constraint code

4.2. Organization

Represents an organization in the booking system

4.2.1. type

Type of the organization

Value

VENUE

DEFAULT

Name

Type

Description

Long

Unique identifier for the organization

name^*

String

Name of the organization

publicKey

UUID

Public key used by the renderer to load published schemas

privateKey

UUID

Organization secret issued at creation. v2 endpoints authenticate with the Secret API key from the Editor login response, not with this value.

domain

String

Domain associated with the organization

autologinEnabled

Boolean

Indicates if auto-login is enabled for this organization

appendDomainToLogin

Boolean

Indicates if domain should be appended to login credentials

type

String

Type of the organization

tenantId

Long

Identifier of the tenant

4.3. OrganizationWithUser

Represents a organization with user

4.3.1. type

Type of the organization

Value

VENUE

DEFAULT

Name

Type

Description

Long

Unique identifier for the organization

name^*

String

Name of the organization

publicKey

UUID

Public key used by the renderer to load published schemas

privateKey

UUID

Organization secret issued at creation. v2 endpoints authenticate with the Secret API key from the Editor login response, not with this value.

domain

String

Domain associated with the organization

autologinEnabled

Boolean

Indicates if auto-login is enabled for this organization

appendDomainToLogin

Boolean

Indicates if domain should be appended to login credentials

type

String

Type of the organization

tenantId

Long

Identifier of the tenant

lastName^*

String

Last name of the user

firstName^*

String

First name of the user

password^*

String

Password of the user

email^*

String

Email of the user

4.4. PageOrganization

Name

Type

Description

totalPages

Integer

Number of pages available at the requested page size

totalElements

Long

Number of items across every page

size

Integer

Number of items per page

content

List[Organization]

Items on the returned page

number

Integer

Zero-based index of the returned page

sort

SortObject

Ordering applied to the results

pageable

PageableObject

Paging that produced this page

numberOfElements

Integer

Number of items on this page, which is smaller than the page size on the last page

first

Boolean

Whether this is the first page

last

Boolean

Whether this is the last page

empty

Boolean

Whether the page carries no items

4.5. PageableObject

Name

Type

Description

offset

Long

Number of items skipped before this page

sort

SortObject

Ordering applied to the results

paged

Boolean

Whether paging was applied

pageSize

Integer

Number of items per page

pageNumber

Integer

Zero-based index of the page

unpaged

Boolean

Whether every item was returned at once

4.6. ProblemDetail

Name

Type

Description

type

String

URI reference identifying the problem type

title

String

Human-readable summary of the error category

status

Integer

HTTP status code

detail

String

Human-readable explanation of the error

instance

String

URI of the specific occurrence

timestamp

String

ISO-8601 timestamp

path

String

Request path

errorCode

String

Machine-readable error code

errors

List[ErrorDetail]

Array of detailed field-level errors

4.7. SessionConfigDto

Name

Type

Description

publicSessionsEnabled^*

Boolean

4.8. SortObject

Name

Type

Description

empty

Boolean

Whether the page carries no items

sorted

Boolean

Whether an ordering was applied

unsorted

Boolean

Whether the results come back in no particular order