# Partners API

### 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

<mark style="color:green;">`POST`</mark> `https://api.cymbal.co/v1/partners/events`

Create a set of events for an organization.

#### Headers

| Name                                                     | Type   | Description                     |
| -------------------------------------------------------- | ------ | ------------------------------- |
| Cymbal-Partner-API-Key<mark style="color:red;">\*</mark> | String | Organization's provided API key |

#### Request Body

| Name                                     | Type     | Description     |
| ---------------------------------------- | -------- | --------------- |
| events<mark style="color:red;">\*</mark> | \[Event] | List of events. |

{% tabs %}
{% tab title="201: Created Successfully queued the events to be created." %}

{% endtab %}
{% endtabs %}

#### Request Schema

```json
{
    "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

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

***

## Create orders

<mark style="color:green;">`POST`</mark> `https://api.cymbal.co/v1/partners/orders`

Create a set of orders for a given organization.

#### Headers

| Name                                                     | Type   | Description                     |
| -------------------------------------------------------- | ------ | ------------------------------- |
| Cymbal-Partner-API-Key<mark style="color:red;">\*</mark> | String | Organization's provided API key |

#### Request Body

| Name                                     | Type     | Description     |
| ---------------------------------------- | -------- | --------------- |
| orders<mark style="color:red;">\*</mark> | \[Order] | List of orders. |

{% tabs %}
{% tab title="201: Created Successfully queued the orders to be created." %}

{% endtab %}
{% endtabs %}

#### Request Schema

```json
{
    "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.
* `prefee_price` and `total_price` are the aggregate of all the tickets in that item grouping. For example, if the item is three General Admission tickets at a price of $15 per ticket. Then `total_price` should be $45.

#### Response Schema

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

***

## Create a contact

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | Organization's provided API key |

#### Request Body

| Name                                      | Type    | Description          |
| ----------------------------------------- | ------- | -------------------- |
| contact<mark style="color:red;">\*</mark> | Contact | Contact information. |

{% tabs %}
{% tab title="201: Successfully created the contact." %}

{% endtab %}
{% endtabs %}

#### Request Schema

```json
{
    "contact": {
        "full_name": "John Smith",
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@cymbal.co",
        "phone": "+19594746360",
        "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](/help/segmentation/genres.md)
* `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

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

***

## Get campaign analytics

<mark style="color:green;">`GET`</mark> `https://api.cymbal.co/v1/partners/campaigns/analytics`&#x20;

Retrieve analytical data for your email or SMS campaigns.

#### Headers

| Name                                                     | Type   | Description                     |
| -------------------------------------------------------- | ------ | ------------------------------- |
| Cymbal-Partner-API-Key<mark style="color:red;">\*</mark> | 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

```json
{
    "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cymbal.co/help/partners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.