Partners API

Cymbal provides multiple REST API endpoints for uploading an organization's events, orders, and contacts.

Authentication

The Cymbal Partners API requires an API token for authentication. This API token must be created within the Cymbal manager for a given organization.

  1. Create an organization in the manager: https://manager.cymbal.co

  2. Generate an API token for the given partner: https://manager.cymbal.co/settings/integrations

  3. Pass the API token in the Cymbal-Partner-API-Key header in every API request.

API tokens can be revoked by an organization within the manager. If API requests return a 403 status code, you will need to generate a new API token.

Create events.

POST https://api.cymbal.co/v1/partners/events

Create a set of events for an organization.

Headers

Name
Type
Description

Cymbal-Partner-API-Key*

String

Organization's provided API key

Request Body

Name
Type
Description

events*

[Event]

List of events.

Request Schema

{
    "events": [
        {
            "id": "12345",
            "url": "https://bellyupaspen.com/head-and-the-heart/tickets",
            "name": "The Head & The Heart",
            "image_url": "https://bellyupaspen.com/wp-content/uploads/2023/08/THATH_960x540_See.jpg",
            "description": "Head & the Heart performing live at the Belly Up Aspen.",
            "tags": ["Folk", "Accoustic"],
            "status": "live",
            "start_datetime": "2024-03-02T15:30:00Z",
            "end_datetime": "2024-03-02T18:00:00Z",
            "doors_open_datetime": "2024-03-02T14:30:00Z",
            "location": {
                "name": "Belly Up Aspen",
                "address": "450 S Galena St, Aspen, CO 81611"
            },
            "ticket_types": [
                {
                    "name": "Standard Admission",
                    "prefee_price": 30.00,
                    "total_price": 40.00,
                    "currency_code": "USD",
                    "quantity": 150
                }
            ]
        }
    ]
}

Required Fields:

  • id

  • url

  • name

  • image_url

  • start_datetime

  • location

Notes:

  • status options: live | canceled

  • datetime format: 2024-03-02T15:30:00Z in UTC

Response Schema

{
    "code": 0,
    "message": "success"
}

Create orders.

POST https://api.cymbal.co/v1/partners/orders

Create a set of orders for a given organization.

Headers

Name
Type
Description

Cymbal-Partner-API-Key*

String

Organization's provided API key

Request Body

Name
Type
Description

orders*

[Order]

List of orders.

Request Schema

{
    "orders": [
        {
            "id": "12345",
            "event_id": "12345",
            "customer": {
                "email": "john.smith@cymbal.co",
                "phone": "12345678900",
                "first_name": "John",
                "last_name": "Smith",
                "address": "123 Main Street, San Francisco, CA, 94110",
                "ip_address": "216.24.84.248"
            },
            "marketing_opt_ins": {
                "email": true,
                "sms": false
            },
            "items": [
                {
                    "ticket_type_name": "Standard Admission",
                    "quantity": 2,
                    "prefee_price": 60.00,
                    "total_price": 80.00,
                    "currency_code": "USD"
                }
            ],
            "created_at": "2024-03-02T15:30:00Z"
        }
    ]
}

Required Fields:

  • id

  • event_id

  • customer

  • marketing_opt_ins

  • items

Notes:

  • customer fields: only one of phone or email is required

  • item fields: currency_code is optional. USD is the default

  • address can just be a zip code.

Response Schema

{
    "code": 0,
    "message": "success"
}

Subscribe contacts.

POST https://api.cymbal.co/v1/partners/subscribe

Subscribe a given contact to either email or SMS communication.

Headers

Name
Type
Description

Cymbal-Partner-API-Key*

String

Organization's provided API key

Request Body

Name
Type
Description

contact*

Contact

Contact information.

Request Schema

{
    "contact": {
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@cymbal.co",
        "phone": "+19594746360",
        "tags": [
             "Tag 1",
             "Tag 2"
         ],
        "genres": [
            "Rock",
            "Dance/Electronic"
        ]
    },
    "ticket_url": "https://www.ticketmaster.com/e/12345678"
}

Required fields:

  • one of phone and/or email is required; all other fields are optional

Notes:

  • customer fields: only one of phone or email is required

  • tags must be created within the Cymbal manager first

  • genres must match one of Cymbal's required list of genres: Genres

  • ticket_url is optional and is used for subscribe forms that are embedded on an event page

Response Schema

{
    "code": 0,
    "message": "success"
}

PreviousHow does billing work?NextPricing

Last updated