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.

201: Created Successfully queued the events to be created.

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"
            },
            "performers": ["The Head & The Heart"],
            "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.

201: Created Successfully queued the orders to be created.

Request Schema

{
    "orders": [
        {
            "id": "12345",
            "event_id": "12345",
            "customer": {
                "email": "[email protected]",
                "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"
}

---

Create contact.

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

Create a new contact and subscribe them to either email or SMS marketing communication.

Headers

Name	Type	Description
Cymbal-Partner-API-Key*	String	Organization's provided API key

Request Body

Name	Type	Description
contact*	Contact	Contact information.

201: Successfully created the contact.

Request Schema

{
    "contact": {
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone": "[phone]",
        "list_id": 1,
        "tags": [
             "Tag 1",
             "Tag 2"
         ],
        "genres": [
            "Rock",
            "Dance/Electronic"
        ]
    },
    "opt_ins": {
        "email": true | false | null,
        "sms": true | false | null
    },
    "interested_in_event_id": "12345"
}

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

• opt_ins tell Cymbal how to update the subscription status of the contact.

  • true will subscribe the contact to either email or SMS marketing communication

  • false will unsubscribe them

  • null will leave the subscription status unchanged

• list_id can be found in the Audience tab by clicking on a list and looking at the URL

• tags must be created within the Cymbal manager first

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

• interested_in_event_id is optional and is used to mark the contact as interested in the event

Response Schema

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

---

Subscribe contacts. - DEPRECATED

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.

201: Successfully subscribed the given contact.

Request Schema

{
    "contact": {
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone": "[phone]",
        "list_id": 1,
        "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

• list_id can be found in the Audience tab by clicking on a list and looking at the URL

• 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"
}