# Spotify Conversions API Reference

{% hint style="warning" %}
The Spotify Conversions API destination is currently in Early Access. Please contact <support@freshpaint.io> for more information about this integration.
{% endhint %}

## Destination Info

* Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Refer to this destination as **Spotify Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object)
* Connection Modes:

<table><thead><tr><th width="200.33333333333331" align="right"> </th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side</th></tr></thead><tbody><tr><td align="right">Web</td><td>false</td><td>true</td></tr><tr><td align="right">Mobile</td><td>false</td><td>true</td></tr><tr><td align="right">Server</td><td>false</td><td>true</td></tr></tbody></table>

This is a reference document for the Snapchat destination. For information on how to set up this integration, see the [spotify-conversions-api-quick-start-guide](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/spotify-conversions-api-early-access/spotify-conversions-api-quick-start-guide "mention").

## Events

When you send an event to the Spotify Conversions API destination from Freshpaint, Freshpaint will create an event in the Spotify event manager by hitting Spotify's API.

### Event Properties

<table data-full-width="true"><thead><tr><th width="179.2666015625">Freshpaint property</th><th width="191.19317626953125">Spotify parameter</th><th width="255.7099609375">Type</th><th width="130.4307861328125">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>spotify_event_name</code></td><td><code>event_name</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td><p>The Spotify event name to track. *See below chart for all values.</p><p></p><p>Note: If this property is absent, Freshpaint will attempt to use the name of the Freshpaint event. This will only work if the Freshpaint event name is one of the specific supported Spotify names, so we recommend sending event name separately.</p></td></tr><tr><td><code>$action_source</code></td><td><code>action_source</code></td><td>string</td><td>Optional</td><td>The medium through which the conversion was made.<br><br>Valid values:<br>"WEB", "OFFLINE", "APP"</td></tr><tr><td><code>opt_out_targeting</code></td><td><code>opt_out_targeting</code></td><td>boolean</td><td>Optional</td><td>If true, the event will not be used for retargeting, only for attribution.<br><br>If this value is not sent, Freshpaint will default to true.</td></tr><tr><td><code>event_source_url</code></td><td><code>event_source_url</code></td><td>string</td><td>Optional</td><td>The URL where the event occurred, must start with "http://" or "https://".</td></tr><tr><td><code>$event_id</code></td><td><code>event_id</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>Unique identifier for the event chosen by the advertiser, used for deduplication.<br><br>Freshpaint will autofill this value.</td></tr><tr><td><code>$event_time</code></td><td><code>event_time</code></td><td>long</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>RFC 3339 timestamp when the event occurred. Must be in the past.<br><br>Freshpaint will autofill this value if missing.</td></tr></tbody></table>

### Accepted Event Names

\*Spotify only accepts particular strings for valid `event_name` values, but they are currently not referenced in their API documentation. Use the below chart for valid names:

| Spotify event\_name Values | Description                                                                                                                                                                                                                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ADD_TO_CART`              | The action of adding an item to a virtual shopping cart or basket. For example, clicking an Add to Cart button on a website, but not actually completing the purchase transaction.                                                                                                 |
| `ALIAS`                    | Sends the advertiser’s customer details to Spotify (email, phone number).                                                                                                                                                                                                          |
| `LEAD`                     | The submission of information about a person or company that has expressed some form of interest in a product or service. For example, submitting an email address to sign up for a newsletter. Note that lead can mean different things depending on the advertiser and industry. |
| `VIEW`                     | The act of landing on or viewing a specific page on a website. For example, landing on the website’s homepage or browsing a specific product page                                                                                                                                  |
| `PURCHASE`                 | The completion of an online purchase transaction, usually signified by receiving order or purchase confirmation, or a transaction receipt. For example, landing on a Thank You or Order Confirmation page.                                                                         |
| `SIGN_UP`                  | Measures the action of signing up or registering for an event, product, service, etc.                                                                                                                                                                                              |
| `PRODUCT`                  | <p>Measures the action of someone viewing a webpage dedicated to a specific product. <br></p><p>Best practices: </p><ul><li>This event code must be installed on every product page that the advertiser is looking to measure.</li></ul>                                           |
| `CHECK_OUT`                | Measures when a user has initiated the online checkout process.                                                                                                                                                                                                                    |
| `CUSTOM_EVENT_1`           | Measures bespoke or custom event actions on a website that are not available as one of Spotify’s standard event types. These are events that you define yourself.                                                                                                                  |
| `CUSTOM_EVENT_2`           | Measures bespoke or custom event actions on a website that are not available as one of Spotify’s standard event types. These are events that you define yourself.                                                                                                                  |
| `CUSTOM_EVENT_3`           | Measures bespoke or custom event actions on a website that are not available as one of Spotify’s standard event types. These are events that you define yourself.                                                                                                                  |
| `CUSTOM_EVENT_4`           | Measures bespoke or custom event actions on a website that are not available as one of Spotify’s standard event types. These are events that you define yourself.                                                                                                                  |
| `CUSTOM_EVENT_5`           | Measures bespoke or custom event actions on a website that are not available as one of Spotify’s standard event types. These are events that you define yourself.                                                                                                                  |

### User Data Properties

When you send user actions to Spotify, Spotify will attempt to match those actions to a particular Spotify user.&#x20;

Spotify requires a number of the user parameters to be hashed. Freshpaint will automatically hash these user values when sending them to Spotify's API.

Spotify also requires a number of normalization rules. The Freshpaint integration will automatically normalize most user data fields according to Spotify's requirements.

{% hint style="warning" %}
Note: although listed as Recommended, **at least one of the following user properties is required by Spotify**: `$ip`, `email`, `$device_id`, or `phone`, with their documentation advising to include ip and device ID when possible.
{% endhint %}

<table data-full-width="true"><thead><tr><th width="160.6484375">Freshpaint property</th><th>Snapchat parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>$ip</code></td><td><code>ip_address</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>IP address of the customer’s device.</td></tr><tr><td><code>email</code></td><td><code>hashed_emails</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>The email of the user.<br><br>Note: Freshpaint will send the hashed value to Spotify.  <strong>You should not hash these values</strong> when sending to Freshpaint. </td></tr><tr><td>$<code>device_id</code></td><td><code>device_id</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>Raw device id of the customer device.</td></tr><tr><td><code>phone</code></td><td><code>hashed_phone_number</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>The phone number of the user.<br><br>Note: Freshpaint will send the hashed value to Spotify.  <strong>You should not hash these values</strong> when sending to Freshpaint.</td></tr><tr><td><code>$user_agent</code></td><td><code>user_agent</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user agent of the browser where the event occurred.</td></tr><tr><td><code>gender</code></td><td><code>gender</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Gender of the user. Snapchat only accepts <code>MALE</code> or <code>FEMALE</code>.</td></tr><tr><td><code>request_ip_address</code></td><td><code>request_ip_address</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's IP address when the request was made.</td></tr><tr><td><code>event_ip_address</code></td><td><code>event_ip_address</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's IP address when the event occured. </td></tr><tr><td><code>platform_id</code></td><td><code>platform_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The ID of the platform.</td></tr><tr><td><code>session_id</code></td><td><code>session_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The ID of the user session.</td></tr><tr><td><code>alias_id</code></td><td><code>alias_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>A unique ID for the alias of the user.</td></tr><tr><td><code>cookie1</code></td><td><code>cookie1</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>First party cookie value used for user match rate.</td></tr><tr><td><code>page_id</code></td><td><code>page_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The ID of the page.</td></tr><tr><td><code>connection_type</code></td><td><code>connection_type</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The type of connection.</td></tr><tr><td><code>age_group</code></td><td><code>age_group</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The age group of the user.</td></tr><tr><td><code>$spclid</code></td><td><code>clickID</code></td><td>string</td><td><mark style="color:$primary;"><strong>Required</strong></mark><strong> for Click Through Conversions</strong></td><td>Spotify's click ID, used for attribution of clicks to conversion events.</td></tr></tbody></table>

### Event Details Properties

<table data-full-width="true"><thead><tr><th width="272.3600769042969">Freshpaint property</th><th width="259.16693115234375">Snapchat parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td><code>amount</code></td><td>float64</td><td><mark style="color:$primary;"><strong>Required</strong></mark> <strong>for PURCHASE events</strong></td><td>Monetary value of purchase.</td></tr><tr><td><code>currency</code></td><td><code>currency</code></td><td>string</td><td><mark style="color:$primary;"><strong>Required</strong></mark> <strong>for PURCHASE events</strong></td><td>ISO 4217 currency code of purchase (e.g., USD, CAD).</td></tr><tr><td><code>content_name</code></td><td><code>content_name</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Name of the product or page involved in the event.</td></tr><tr><td><code>content_category</code></td><td><code>content_category</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Category of the content, should align with Google's Product Taxonomy.</td></tr></tbody></table>