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

2. Generate an API token for the given partner

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 a 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": {
        "event_id": "123456",
        "ticketer": "eventbrite"
    }
}

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 is optional and is used to mark the contact as interested in the event

  • ticketer must be one of our supported ticketing providers. Reach out to our team to get the appropriate value for your use-case.

Response Schema

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

---

Get campaign analytics

GET https://api.cymbal.co/v1/partners/campaigns/analytics

Retrieve analytical data for your email or SMS campaigns.

Headers

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

Query Parameters

Name	Type	Description
page	Integer	Page number of campaigns to return. Default value is 1.
per_page	Integer	Number of records to return per page. Default value is 10.
type	Enum	Type of campaigns to return. Type can be email or sms. Returns both email and sms campaigns if empty.

Response Schema

{
    "code": 0,
    "message": "success",
    "response": [
        {
            "campaign_id": 1,
            "campaign_name": "My campaign",
            "campaign_subject_line": "Subject Line",
            "campaign_type": "email",
            "delivered_at": "2026-01-02T19:44:19.738783Z",
            "num_recipients": 100,
            "num_opens": 50,
            "num_links_clicked": 40,
            "num_unsubscribes": 1,
            "num_undelivered": 0,
            "attributed_tickets_sold": 4,
            "attributed_revenue": 1000
        }
    ]
}

Notes:

• attributed_revenue represents the campaign's attributed revenue amount in cents

• num_links_clicked is the number of unique recipients who clicked a link in a campaign