Tixbase Swagger

API Endpoint Handover Template

1. General Information

API Overview

Welcome to the Tixbase Core API – a comprehensive white-label ticketing solution that enables organizations to manage events and tickets with blockchain integration.

This API provides complete functionality for:

• Event creation and management
• Primary ticket sales processing
• Secondary market ticket operations
• NFT-backed ticket creation and validation
• Secure resale mechanisms

Authentication

All API endpoints require authentication using an organization-specific API key. Include your API key in the request header:

x-api-key: tixbase_<your-api-key>

Example:

x-api-key: tixbase_f55fe43c5bcf40345f64dd78d7575e7426e1622a8bdd45e7f693c843265c007c

Base URLs

Development:

https://core-api.dev.tixbase.io/api/v1

Staging:

https://core-api.staging.tixbase.io/api/v1

---

2. API Endpoint Details

1. Create Event

Endpoint URL:

POST /events

Description:

Creates a new event with either fixed pricing or category-based pricing. Events must be classified as either:

• Seated Events: Require seat and row assignments for all tickets
• General Admission: No seat or row assignments needed

Event categories are restricted to: football, music, performing_arts, sports, museum, or other.

Pricing can be handled in two ways:

1. Fixed price: All tickets have the same price
2. Category-based: Different ticket categories with varying prices defined during event creation

Input Parameters (Request Body):

Parameter	Type	Required	Description
externalEventId	String	✅ Yes	Unique identifier for the event
name	String	✅ Yes	Name of the event
date	String	✅ Yes	Event start date and time (ISO 8601)
eventType	String	✅ Yes	Either 'seated' or 'general_admission'
eventCategory	String	✅ Yes	One of: 'football', 'music', 'performing_arts', 'sports', 'museum', 'other'
maxTickets	Integer	✅ Yes	Maximum number of tickets available
resaleEnabled	Boolean	✅ Yes	Whether ticket resale is allowed
price	Number	Conditional	Fixed price for all tickets (required if not using ticketCategories)
endTime	String	❌ No	Event end time (ISO 8601)
venueName	String	❌ No	Name of the venue
venueAddressStreet	String	❌ No	Venue street address
venueAddressCity	String	❌ No	Venue city
venueAddressState	String	❌ No	Venue state/region
venueAddressPostalCode	String	❌ No	Venue postal code
venueAddressCountry	String	❌ No	Venue country
description	String	❌ No	Event description
purchaseLimit	Integer	❌ No	Maximum tickets per purchase
eventImage	String	❌ No	Base64 encoded event image
ticketCategories	Array	Conditional	Array of ticket categories (required if not using fixed price)

Request Body Example:

{
  "externalEventId": "EVT123456",
  "name": "Concert Night",
  "date": "2025-05-10T20:00:00Z",
  "eventType": "seated",
  "endTime": "2025-05-10T23:00:00Z",
  "eventCategory": "music",
  "venueName": "Main Arena",
  "venueAddressStreet": "123 Main St",
  "venueAddressCity": "Berlin",
  "venueAddressState": "BE",
  "venueAddressPostalCode": "10115",
  "venueAddressCountry": "Germany",
  "description": "An amazing live music event",
  "purchaseLimit": 4,
  "eventImage": "iVBORw0KGgoAAAANSUhEUgAA...",
  "maxTickets": 5000,
  "resaleEnabled": true,
  "ticketCategories": [
    {
      "name": "VIP",
      "price": 100.0,
      "maxTickets": 500
    },
    {
      "name": "Standard",
      "price": 50.0,
      "maxTickets": 4500
    }
  ]
}

Example cURL Command:

curl -X POST "https://core-api.staging.tixbase.io/api/v1/events" \
     -H "Content-Type: application/json" \
     -H "x-api-key: tixbase_<your-api-key>" \
     -d '{
       "externalEventId": "EVT123456",
       "name": "Concert Night",
       "date": "2025-05-10T20:00:00Z",
       "eventType": "seated",
       "maxTickets": 5000,
       "resaleEnabled": true,
       "eventCategory": "music",
       "ticketCategories": [
         {
           "name": "VIP",
           "price": 100.0,
           "maxTickets": 500
         },
         {
           "name": "Standard",
           "price": 50.0,
           "maxTickets": 4500
         }
       ]
     }'

Response Example:

{
  "eventId": "a84489ea-23dc-40bd-b65e-f984fcfd5ae3",
  "organizationId": "c1be3004-7637-44bc-944f-663141be2a6d",
  "externalEventId": "EVT123456",
  "name": "Concert Night",
  "date": "2025-05-10T20:00:00.000Z",
  "eventCategory": "music",
  "eventType": "seated",
  "maxTickets": 5000,
  "resaleEnabled": true,
  "contractAddress": "0x88688348E0B2f3126dA73967594186e494F9D856",
  "status": "active"
}

2. Create Ticket

Endpoint URL:

POST /tickets/create

Description:

Creates a new ticket for an event. Requirements vary based on event type:

• For seated events: seat and row numbers are mandatory
• For general admission: seat and row should not be included
• For events with ticket categories: categoryName is required to determine pricing

Input Parameters (Request Body):

Parameter	Type	Required	Description
externalTicketId	String	✅ Yes	Unique identifier for the ticket
externalEventId	String	✅ Yes	Event identifier the ticket belongs to
externalOwnerId	String	✅ Yes	Identifier of the ticket owner
ownerEmailAddress	String	✅ Yes	Email address of the ticket owner
seat	Integer	Conditional	Required for seated events only
row	Integer	Conditional	Required for seated events only
categoryName	String	Conditional	Required for events with ticket categories

Request Body Example:

{
  "externalTicketId": "TICKET123",
  "externalEventId": "EVT123456",
  "seat": 10,
  "row": 5,
  "externalOwnerId": "USER789",
  "ownerEmailAddress": "[email protected]",
  "categoryName": "VIP"
}

Example cURL Command:

curl -X POST "https://core-api.staging.tixbase.io/api/v1/tickets/create" \
     -H "Content-Type: application/json" \
     -H "x-api-key: tixbase_<your-api-key>" \
     -d '{"externalTicketId":"TICKET123","externalEventId":"EVT123456","seat":10,"row":5,"externalOwnerId":"USER789","ownerEmailAddress":"[email protected]","categoryName":"VIP"}'

Response Example:

{
  "message": "Ticket and NFT created successfully",
  "status": "not_for_sale",
  "ticketId": "de27cccd-f133-466c-bfb7-1aff8c45e239",
  "externalTicketId": "TICKET123",
  "eventId": "a84489ea-23dc-40bd-b65e-f984fcfd5ae3",
  "categoryId": "b5fdaa17-b40e-4153-8f4b-212e7bab98f6",
  "ownerId": "9e88391c-2650-403b-88ba-d10c8e499983",
  "externalOwnerId": "USER789"
}

3. Create Tickets

Endpoint URL:

POST /tickets/createBatch

Description:

Creates multiple new tickets for an user for a specific event. Requirements vary based on event type:

• For seated events: seat and row numbers are mandatory
• For general admission: seat and row should not be included
• For events with ticket categories: categoryName is required to determine pricing

Input Parameters (Request Body):

Parameter	Type	Required	Description
externalEventId	String	✅ Yes	Event identifier the ticket belongs to
externalOwnerId	String	✅ Yes	Identifier of the ticket owner
ownerEmailAddress	String	✅ Yes	Email address of the ticket owner
tickets	Array of Ticket	✅ Yes

Ticket:

Parameter	Type	Required	Description
externalTicketId	String	✅ Yes	Unique identifier for the ticket
seat	Integer	Conditional	Required for seated events only
row	Integer	Conditional	Required for seated events only
categoryName	String	Conditional	Required for events with ticket categories

Request Body Example:

{
  "externalEventId": "EVT123456",
  "externalOwnerId": "USER789",
  "ownerEmailAddress": "[email protected]",
  "tickets": [
    {
      "externalTicketId": "TICKET123",
      "seat": 10,
      "row": 5,
      "categoryName": "VIP"
    },
    {
      "externalTicketId": "TICKET456",
      "seat": 3,
      "row": 44,
      "categoryName": "Standard"
    }
  ]
}

Example cURL Command:

curl -X POST "https://core-api.staging.tixbase.io/api/v1/tickets/createBatch" \
     -H "Content-Type: application/json" \
     -H "x-api-key: tixbase_<your-api-key>" \
     -d '{"externalEventId":"EVT123456","externalOwnerId":"USER789","ownerEmailAddress":"[email protected]","tickets":[{"externalTicketId":"TICKET123","seat":10,"row":5,"categoryName":"VIP"},{"externalTicketId":"TICKET456","seat":3,"row":44,"categoryName":"Standard"}]}'

Response Example:

{
  "message": "Tickets and NFTs created successfully",
  "tickets": [
    {
      "status": "not_for_sale",
      "ticketId": "de27cccd-f133-466c-bfb7-1aff8c45e239",
      "externalTicketId": "TICKET123",
      "eventId": "a84489ea-23dc-40bd-b65e-f984fcfd5ae3",
      "categoryId": "b5fdaa17-b40e-4153-8f4b-212e7bab98f6",
      "ownerId": "9e88391c-2650-403b-88ba-d10c8e499983",
      "externalOwnerId": "USER789"
    },
    {
      "status": "not_for_sale",
      "ticketId": "c1b8bbe2-01c4-4dfd-99ef-003ad384bb4b",
      "externalTicketId": "TICKET123",
      "eventId": "a84489ea-23dc-40bd-b65e-f984fcfd5ae3",
      "categoryId": "fddc60c2-8252-4fa0-b30d-58fcfe728071",
      "ownerId": "9e88391c-2650-403b-88ba-d10c8e499983",
      "externalOwnerId": "USER789"
    }
  ]
}

4. Transfer Ticket

Endpoint URL:

POST /tickets/transfer-ticket

Description:

Transfers a ticket to a new owner. If the recipient (identified by externalUserId and emailAddress) doesn't exist in the system, a new user account will be automatically created.

Input Parameters (Request Body):

Parameter	Type	Required	Description
externalUserId	String	✅ Yes	Current ticket owner's identifier
externalTicketId	String	✅ Yes	Identifier of ticket to transfer
recipient.externalUserId	String	✅ Yes	New owner's identifier
recipient.emailAddress	String	✅ Yes	New owner's email address

Request Body Example:

{
  "externalUserId": "USER789",
  "externalTicketId": "TICKET123",
  "recipient": {
    "externalUserId": "USER456",
    "emailAddress": "[email protected]"
  }
}

Example cURL Command:

curl -X POST "https://core-api.staging.tixbase.io/api/v1/tickets/transfer-ticket" \
     -H "Content-Type: application/json" \
     -H "x-api-key: tixbase_<your-api-key>" \
     -d '{"externalUserId":"USER789","externalTicketId":"TICKET123","recipient":{"externalUserId":"USER456","emailAddress":"[email protected]"}}'

Response Example:

{
  "blockNumber": 6651,
  "transactionHash": "0x69a77e54910de831c987c7a713dc99a4a51113f5dc3c74e2e3e6d89399eec1d0",
  "recipient": {
    "userId": "2524e6da-613f-4c15-9b2b-85c56d3f0363",
    "externalUserId": "USER456",
    "walletAddress": "0xa9056b7a5a74cf24322768e009084122cfc80918"
  }
}

5. Ticket Metadata

Endpoint URL:

POST /tickets/metadata/{externalTicketId}

Description:

Get ticket metadata

Input Parameters (Request Params):

Parameter	Type	Required	Description
externalTicketId	String	✅ Yes	Identifier of ticket

Example cURL Command:

curl -X POST "https://core-api.staging.tixbase.io/api/v1/tickets/metadata/TICKET123" \
     -H "x-api-key: tixbase_<your-api-key>"

6. Additional Notes & Best Practices

• Rate Limits: Requests may be rate-limited to prevent abuse; consult API documentation for specifics.
• Security Measures: Ensure that all requests include the correct x-api-key and are securely transmitted over HTTPS.
• Testing Environment:
  • Development: https://core-api.dev.tixbase.io/api/v1
  • Staging: https://core-api.staging.tixbase.io/api/v1

For further information, please refer to the full API documentation or contact Tixbase support.