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

#### 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](https://docs.cymbal.co/help/segmentation/genres "mention")
* `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