Booking API v1
|
This is the legacy v1 API documentation. This version is maintained for backward compatibility but new integrations should use API v2. Please migrate to v2: |
1. Overview
Version: 1.64.0-dev.53-feb9164c
1.1. Seatmap.pro Booking API v1 (Legacy)
Legacy API providing unified CRUD operations for event and pricing management. Version 2 is recommended for new integrations with enhanced features and improved architecture.
1.1.1. Core Operations
-
Events - Create, read, update, and delete event configurations
-
Venues - Retrieve venue and schema information
-
Prices - Manage pricing structures and assignments
-
Booking - Lock and unlock seats for reservation workflows
-
Price Assignments - Assign prices to specific seats
1.1.2. Authentication
All requests require API key authentication: [source]
X-API-Key: {sessionId}
The session ID is provided during authentication and must be included in every request header.
1.1.3. Migration Notice
Version 1 is in maintenance mode. New features and improvements are exclusively available in Version 2. Consider migrating to v2 for:
-
Simplified identifiers (single Long/UUID vs composite keys)
-
Enhanced error responses with field-level details (RFC 7807)
-
Bulk operations for improved performance
-
Better data integrity and validation
-
Extended pagination support
-
Schema cloning capabilities
2. Authentication
2.1. API Key
All requests must include the API key in the header:
-
Header:
X-API-Key -
Location: HTTP Header
curl -X GET "https://api.seatmap.pro/api/private/v1.0/..." \
-H "X-API-Key: your-api-key"3. API Endpoints
3.1. Booking
Allows to the system lock ans unlock seats
3.1.1. lock
POST /api/private/v1.0/booking/lock
Lock a seat or GA
|
Seat should be available |
Body Parameter
Name |
Description |
Required |
Default |
Selection |
X |
Query Parameters
Name |
Description |
Required |
Default |
id |
X |
null |
Return Type
array[Selection]
Responses
Code |
Message |
Datatype |
200 |
Returns unsuccessful attempts |
List[Selection] |
400 |
Input data is not valid |
List[Selection] |
403 |
Forbidden. Please use correct private key. |
List[Selection] |
Examples
HTTP Request
cURL Request
HTTP Response
3.1.2. sale
POST /api/private/v1.0/booking/sale
Transfer seat or GA to the state sold
|
This feature applicable only in a sales control mode |
Body Parameter
Name |
Description |
Required |
Default |
Selection |
X |
Query Parameters
Name |
Description |
Required |
Default |
id |
X |
null |
Return Type
array[Selection]
Responses
Code |
Message |
Datatype |
200 |
Returns unsuccessful attempts |
List[Selection] |
400 |
Input data is not valid |
List[Selection] |
403 |
Forbidden. Please use correct private key. |
List[Selection] |
Examples
HTTP Request
cURL Request
HTTP Response
3.1.3. unlock
POST /api/private/v1.0/booking/unlock
Unlock a seat or GA
|
For GA unlocking capacity counter shall be specified |
Body Parameter
Name |
Description |
Required |
Default |
Selection |
X |
Query Parameters
Name |
Description |
Required |
Default |
id |
X |
null |
Return Type
array[Selection]
Responses
Code |
Message |
Datatype |
200 |
Returns unsuccessful attempts |
List[Selection] |
400 |
Input data is not valid |
List[Selection] |
403 |
Forbidden. Please use correct private key. |
List[Selection] |
Examples
HTTP Request
cURL Request
HTTP Response
3.2. EventsV1Deprecated
Legacy event management endpoints for API v1.
DEPRECATED: This API version is maintained for backward compatibility only. New integrations should use API v2: /api/private/v2.0/events/
Migration benefits: * Improved performance with optimized queries * Enhanced filtering and pagination * Better error messages and validation * UUID-based identifiers for better scalability
See migration guide: https://seatmap.pro/knowledge-base/api/migration/v1-to-v2
3.2.1. eventAll
GET /api/private/v1.0/events/
Retrieve list of all events (v1 - Deprecated)
|
Getting all the events with paging. DEPRECATED: Use GET /api/private/v2.0/events/ instead. V2 API provides standard Spring Data pagination with better filtering options. |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
limit |
Quantity of requested items |
50 |
|
offset |
Offset for the pager |
0 |
Return Type
array[Event]
Responses
Code |
Message |
Datatype |
200 |
Returns list of objects |
List[Event] |
400 |
Input data is not valid |
List[Event] |
403 |
Forbidden. Please use correct private key. |
List[Event] |
Examples
HTTP Request
cURL Request
HTTP Response
3.2.2. eventCreate
POST /api/private/v1.0/events/
Create an Event (v1 - Deprecated)
|
Before you start to create an Event you need to create a schema with venue. DEPRECATED: Use POST /api/private/v2.0/events/ instead. V2 API provides better validation, UUID identifiers, and improved error handling. |
Body Parameter
Name |
Description |
Required |
Default |
Event |
X |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns created object |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.2.3. eventDelete
DELETE /api/private/v1.0/events/{id}
Delete an Event (v1 - Deprecated)
|
Deleted event shall contains valid id. DEPRECATED: Use DELETE /api/private/v2.0/events/{id} instead. V2 API returns proper HTTP 204 No Content on successful deletion. |
Body Parameter
Name |
Description |
Required |
Default |
Path Parameters
Name |
Description |
Required |
Default |
id |
Valid event identifier |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns result of the delete operation |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.2.4. eventUpdate
PUT /api/private/v1.0/events/
Update an Event (v1 - Deprecated)
|
Updated event shall contains valid id. DEPRECATED: Use PUT /api/private/v2.0/events/ instead. V2 API provides better validation and clearer response codes. |
Body Parameter
Name |
Description |
Required |
Default |
Event |
X |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns updated object |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.3. PriceAssignments
Allows to assign/remove prices to seats
3.3.1. assignPrice
POST /api/private/v1.0/assignments/
Assign prices to event
|
Price assignments assume using of plain representation of price. For GA sections you need to specify capacity |
Body Parameter
Name |
Description |
Required |
Default |
PriceAssignment |
X |
Query Parameters
Name |
Description |
Required |
Default |
id |
Corresponding event id |
X |
null |
clean |
Clean before assign is used when you need completely renew the price assignment. It also could be cleaned with clean method |
false |
Return Type
array[PriceAssignment]
Responses
Code |
Message |
Datatype |
200 |
Returns unsuccessful assignments |
List[PriceAssignment] |
400 |
Input data is not valid |
List[PriceAssignment] |
403 |
Forbidden. Please use correct private key. |
List[PriceAssignment] |
Examples
HTTP Request
cURL Request
HTTP Response
3.3.2. cleanAssignment
POST /api/private/v1.0/assignments/clean
Remove all price assignments from event
|
All states including locked seats, will be cleaned up during this operation |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
id |
Corresponding event id |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns true if everything is ok |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.3.3. removeAssignment
DELETE /api/private/v1.0/assignments/
Remove specified assignments from event
|
To remove assignments from event we are using simplified object Selection. For GA sections use capacity field as well |
Body Parameter
Name |
Description |
Required |
Default |
Selection |
X |
Query Parameters
Name |
Description |
Required |
Default |
id |
Corresponding event id |
X |
null |
Return Type
array[Selection]
Responses
Code |
Message |
Datatype |
200 |
Returns unsuccessful attempts to remove assignment |
List[Selection] |
400 |
Input data is not valid |
List[Selection] |
403 |
Forbidden. Please use correct private key. |
List[Selection] |
Examples
HTTP Request
cURL Request
HTTP Response
3.4. Prices
Provides CRUD operations for prices
3.4.1. priceAll
GET /api/private/v1.0/prices/
Retrieve all prices for event
|
All prices |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
id |
X |
null |
Return Type
array[Price]
Responses
Code |
Message |
Datatype |
200 |
Returns list of objects |
List[Price] |
400 |
Input data is not valid |
List[Price] |
403 |
Forbidden. Please use correct private key. |
List[Price] |
Examples
HTTP Request
cURL Request
HTTP Response
3.4.2. priceCreate
POST /api/private/v1.0/prices/
Create a price for event
|
Binds a price to event |
Body Parameter
Name |
Description |
Required |
Default |
Price |
X |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns created object |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.4.3. priceDelete
DELETE /api/private/v1.0/prices/
Delete a price for event
|
Binds a price to event |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
id |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns true if everything is ok. |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.4.4. priceUpdate
PUT /api/private/v1.0/prices/
Update a price for event
|
Binds a price to event |
Body Parameter
Name |
Description |
Required |
Default |
Price |
X |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns updated object |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.5. Venues
Provides descriptions of the existing venues and schemas
3.5.1. schemaAll
GET /api/private/v1.0/venues/schemas/
Retrieve list of all schemas
|
Getting all the schemas with paging |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
limit |
Quantity of requested items |
50 |
|
offset |
Offset for the pager |
0 |
|
venueId |
Venue id |
null |
|
lastUpdated |
Schemas updated after this date will be retrieved. |
null |
Return Type
array[Schema]
Responses
Code |
Message |
Datatype |
200 |
Returns list of schemas |
List[Schema] |
400 |
Input data is not valid |
List[Schema] |
403 |
Forbidden. Please use correct private key. |
List[Schema] |
Examples
HTTP Request
cURL Request
HTTP Response
3.5.2. schemaDetails
GET /api/private/v1.0/venues/schemas/{schemaId}/details/
Retrieve schema’s details
|
Getting schema’s details |
Body Parameter
Name |
Description |
Required |
Default |
Path Parameters
Name |
Description |
Required |
Default |
schemaId |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns schema's details |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.5.3. schemaMetadata
GET /api/private/v1.0/venues/schemas/{schemaId}/
Retrieve schema’s metadata
|
Getting schema’s metadata with \\<\\<#composite-key, Composite Key\\>\\>s |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
numberedSections |
false |
||
useInternalIds |
false |
Path Parameters
Name |
Description |
Required |
Default |
schemaId |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns schema's metadata |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.5.4. sectionMetadata
GET /api/private/v1.0/venues/schemas/{schemaId}/section/{sectionId}/
Retrieve section’s metadata
|
Getting section’s metadata with ID |
Body Parameter
Name |
Description |
Required |
Default |
Path Parameters
Name |
Description |
Required |
Default |
schemaId |
X |
null |
|
sectionId |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns section's metadata |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
3.5.5. venueAll
GET /api/private/v1.0/venues/
Retrieve list of all venues
|
Getting all the venues with paging |
Body Parameter
Name |
Description |
Required |
Default |
Query Parameters
Name |
Description |
Required |
Default |
limit |
Quantity of requested items |
50 |
|
offset |
Offset for the pager |
0 |
Return Type
array[Venue]
Responses
Code |
Message |
Datatype |
200 |
Returns list of objects |
List[Venue] |
400 |
Input data is not valid |
List[Venue] |
403 |
Forbidden. Please use correct private key. |
List[Venue] |
Examples
HTTP Request
cURL Request
HTTP Response
3.5.6. venueById
GET /api/private/v1.0/venues/{venueId}
Retrieves a specific venue by id
|
Getting venue by Id |
Body Parameter
Name |
Description |
Required |
Default |
Path Parameters
Name |
Description |
Required |
Default |
venueId |
X |
null |
Return Type
Responses
Code |
Message |
Datatype |
200 |
Returns list of objects |
|
400 |
Input data is not valid |
|
403 |
Forbidden. Please use correct private key. |
Examples
HTTP Request
cURL Request
HTTP Response
4. Data Models
4.1. Event
Valid event object without id field
Name |
Type |
Required |
Description |
id |
|||
start |
X |
||
killAfter |
|||
name |
X |
||
schemaId |
X |
4.3. Price
Name |
Type |
Required |
Description |
id |
|||
name |
X |
||
eventId |
X |
||
externalId |
4.4. PriceAssignment
Name |
Type |
Required |
Description |
capacity |
|||
compositeKey |
X |
||
price |
X |
||
properties |
4.6. Schema
Name |
Type |
Required |
Description |
id |
|||
capacity |
|||
name |
|||
venueId |
|||
eventId |
4.7. SeatMetadata
Name |
Type |
Required |
Description |
key |
|||
name |
|||
x |
|||
y |
|||
ix |
|||
iy |
4.8. SectorMetadata
Name |
Type |
Required |
Description |
key |
|||
name |
|||
x |
|||
y |
|||
width |
|||
height |
|||
angle |
|||
guid |
|||
rows |
List[[array]] |
||
id |
|||
shapes |
List[[array]] |
||
labelOffsetX |
|||
labelOffsetY |
|||
labelStyle |
4.9. SectorWithCoords
Name |
Type |
Required |
Description |
id |
|||
isGa |
|||
name |
X |
||
x |
|||
y |
|||
guid |
|||
left |
|||
top |
|||
angle |
|||
width |
|||
height |
|||
type |
|||
properties |
|||
shapes |
List[[array]] |
4.11. Shape
4.11.1. textPosition
Value |
TOP |
BOTTOM |
LEFT |
RIGHT |
Name |
Type |
Required |
Description |
id |
|||
width |
|||
height |
|||
y |
|||
x |
|||
angle |
|||
groupOfSeatsGuid |
|||
order |
|||
text |
|||
textPosition |
|||
textColor |
|||
fill |