1. Knowledge base
  2. API Reference

1. Overview

Version: 1.61.1

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-level API tokens

  • 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: TEN:{maskedTenantId}:{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 - Invalid request parameters or validation error

403

Forbidden - Unauthorized access or insufficient permissions

404

Not Found - Requested resource does not exist

500

Internal Server Error - Server encountered an unexpected error

2.2.2. Error Response Format

Error responses include a descriptive message to help diagnose the issue:

{
  "timestamp": "2026-02-13T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for field 'name': must not be blank",
  "path": "/api/private/v2.0/events"
}

2.2.3. Best Practices

  • Always check the HTTP status code before processing the response

  • Implement retry logic for 500-series errors with exponential backoff

  • Log error responses for debugging

  • Handle validation errors (400) by checking the message field

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"

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

Create a organization
Parameters
Body Parameter

Name

Description

Required

Default

OrganizationWithUser

OrganizationWithUser

X
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

ProblemDetail

403

ProblemDetail

500

ProblemDetail
Request Content Type

  • application/json

Examples
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" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10,
  "lastName" : "New User",
  "firstName" : "New User",
  "password" : "71a0e57c-75e1-49f4-be4c-425a8f66aced",
  "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" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "domain" : null,
  "autologinEnabled" : false,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10,
  "lastName" : "New User",
  "firstName" : "New User",
  "password" : "71a0e57c-75e1-49f4-be4c-425a8f66aced",
  "email" : "newuser@test.com"
}'
HTTP Response
HTTP/1.1 201 Created
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 282

{
  "id" : 2,
  "name" : "Test Organization",
  "publicKey" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "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

Delete a organization
Parameters
Body Parameter

Name

Description

Required

Default
Path Parameters

Name

Description

Required

Default

id

X

null
Return Type

-

Content Type

  • application/problem+json

  • application/json

Responses
Table 2. HTTP Response Codes

Code

Message

Datatype

204

Successfully deleted

<<>>

400

ProblemDetail

403

ProblemDetail

404

ProblemDetail

500

ProblemDetail
Examples
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'
HTTP Response
HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains

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

Required

Default
Path Parameters

Name

Description

Required

Default

id

X

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

ProblemDetail

403

ProblemDetail

404

ProblemDetail

500

ProblemDetail
Examples
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'
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 282

{
  "id" : 2,
  "name" : "Test Organization",
  "publicKey" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "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

Required

Default
Query Parameters

Name

Description

Required

Default

page

Zero-based page index (0..N)

0

size

The size of the page to be returned

20

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

ProblemDetail

403

ProblemDetail

500

ProblemDetail
Examples
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'
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 1079

{
  "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" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
    "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
    "domain" : null,
    "autologinEnabled" : false,
    "appendDomainToLogin" : false,
    "type" : "DEFAULT",
    "tenantId" : 10
  } ],
  "pageable" : {
    "pageNumber" : 0,
    "pageSize" : 20,
    "sort" : {
      "sorted" : false,
      "empty" : true,
      "unsorted" : true
    },
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalPages" : 1,
  "totalElements" : 2,
  "first" : true,
  "size" : 20,
  "number" : 0,
  "sort" : {
    "sorted" : false,
    "empty" : true,
    "unsorted" : true
  },
  "numberOfElements" : 2,
  "empty" : false
}

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

Operation: updateOrganization

Update a organization

Update a organization
Parameters
Body Parameter

Name

Description

Required

Default

Organization

Organization

X
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

ProblemDetail

403

ProblemDetail

404

ProblemDetail

500

ProblemDetail
Request Content Type

  • application/json

Examples
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" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "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" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "domain" : null,
  "autologinEnabled" : true,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}'
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Content-Length: 272

{
  "id" : 2,
  "name" : "NEW_NAME",
  "publicKey" : "34bf091f-3545-4065-81d0-0aebb1ac9e4a",
  "privateKey" : "d1e17b9a-5d9c-4d62-a2a0-0824bc7e59e3",
  "domain" : null,
  "autologinEnabled" : true,
  "appendDomainToLogin" : false,
  "type" : "DEFAULT",
  "tenantId" : 10
}

4. Data Models

This section describes all data structures used in the API.

4.1. ErrorDetail

Name

Type

Required

Description

field

[String]

Name of the field that failed validation

message

[String]

Human-readable error message

rejectedValue

[oas_any_type_not_mapped]

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

Required

Description

id

[Long]

Unique identifier for the organization

name

[String]

X

Name of the organization

publicKey

[UUID]

Public key used for authentication

privateKey

[UUID]

Private key used for authentication (hidden in toString)

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

Required

Description

id

[Long]

Unique identifier for the organization

name

[String]

X

Name of the organization

publicKey

[UUID]

Public key used for authentication

privateKey

[UUID]

Private key used for authentication (hidden in toString)

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]

X

Last name of the user

firstName

[String]

X

First name of the user

password

[String]

X

Password of the user

email

[String]

X

Email of the user

4.4. PageOrganization

Name

Type

Required

Description

totalPages

[Integer]

totalElements

[Long]

pageable

PageableObject

first

[Boolean]

last

[Boolean]

size

[Integer]

content

List[[array]]

number

[Integer]

sort

SortObject

numberOfElements

[Integer]

empty

[Boolean]

4.5. PageableObject

Name

Type

Required

Description

paged

[Boolean]

pageNumber

[Integer]

pageSize

[Integer]

offset

[Long]

sort

SortObject

unpaged

[Boolean]

4.6. ProblemDetail

Name

Type

Required

Description

type

[String]

URI reference identifying the problem type

title

[String]

Human-readable summary of the error category

status

[oas_any_type_not_mapped]

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[[array]]

Array of detailed field-level errors

4.7. ProblemDetailErrorsInner

Name

Type

Required

Description

field

[String]

Name of the field that failed validation

message

[String]

Human-readable error message

rejectedValue

[oas_any_type_not_mapped]

code

[String]

Validation constraint code

4.8. SortObject

Name

Type

Required

Description

sorted

[Boolean]

empty

[Boolean]

unsorted

[Boolean]

5. Additional Resources