# Snapchat Conversions API Reference

{% hint style="warning" %}
The Snapchat 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 **Snapchat** 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 [snapchat-conversions-api-quick-start-guide](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/snapchat-conversions-api/snapchat-conversions-api-quick-start-guide "mention").

## Events

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

### Event Name

Snapchat only supports a subset of valid event names. You can find the most up to date list in [Snapchat's API documentation](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#server-parameters).

You can either pass this value explicitly in the `snapchat_event_name` property or name your Freshpaint event one of these valid names. You can also set up a [Transformation](https://documentation.freshpaint.io/admin-panel/transformations) to rename your event to instead be one of these names for the Snapchat destination.

* ACHIEVEMENT\_UNLOCKED
* AD\_CLICK
* AD\_VIEW
* ADD\_BILLING
* ADD\_CART
* ADD\_TO\_WISHLIST
* APP\_INSTALL
* APP\_OPEN
* COMPLETE\_TUTORIAL
* CUSTOM\_EVENT\_1, CUSTOM\_EVENT\_2, CUSTOM\_EVENT\_3, \
  CUSTOM\_EVENT\_4, or CUSTOM\_EVENT\_5
* INVITE
* LEVEL\_COMPLETE
* LIST\_VIEW
* LOGIN
* PAGE\_VIEW
* PURCHASE
* RATE
* RESERVE
* SEARCH
* SHARE
* SIGN\_UP
* SPENT\_CREDITS
* START\_CHECKOUT
* START\_TRIAL
* SUBSCRIBE
* VIEW\_CONTENT

### Required Properties

<table data-full-width="true"><thead><tr><th>Freshpaint property</th><th width="191.19317626953125">Snapchat parameter</th><th>Type</th><th width="184.6378173828125">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>snapchat_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 Snapchat event name to track. See <a href="https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#server-parameters">Snapchat's API documentation</a> for the list of allowed event names.</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 Snapchat names, so we recommend sending event name separately.</p></td></tr><tr><td><code>$sccid</code></td><td><code>sc_click_id</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>The Snapchat click ID. Retrieved from the <code>ScCid</code> or <code>sccid</code> query parameter in the URL of your website.</td></tr><tr><td><code>$ip</code></td><td><code>client_ip_address</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>IP address from device that sent the conversion event.</td></tr><tr><td><code>$user_agent</code></td><td><code>client_user_agent</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>The user agent of the browser where the event occurred.</td></tr><tr><td><code>$current_url</code></td><td><code>event_source_url</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td><p>The URL of the page where the event took place.</p><p></p><p>Note: In <a href="https://documentation.freshpaint.io/readme/hipaa-mode">HIPAA Mode</a>, the URL will be redacted by Freshpaint if this field is not added to the allowlist to remove any potential PHI in the URL. To send the complete URL to Snapchat, add the <code>$current_url</code> property to your HIPAA allowlist.</p></td></tr><tr><td><code>action_source</code></td><td><code>action_source</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark></td><td>Where the event took place. Accepted values are:<br>WEB<br>OFFLINE<br>MOBILE_APP<br><br>Note: Freshpaint will automatically set this value if it is not manually set on the event, based on what Freshpaint library is used to trigger the event (and defaulting to Web).</td></tr><tr><td><code>currency</code></td><td><code>currency</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark> for PURCHASE events</td><td>This represents the currency associated with the value provided. <a href="https://app.gitbook.com/u/szeFQuZTeyYJrECkeCMR0Xr6OPM2">Subset of standard ISO 4217 code supported</a>.</td></tr><tr><td><code>value</code></td><td><code>value</code></td><td>string</td><td><mark style="color:$danger;"><strong>Required</strong></mark> for PURCHASE events</td><td>This numeric value is associated with the specific event.</td></tr></tbody></table>

### User Data Properties

When you send user actions to Snapchat, Snapchat will attempt to match those actions to a particular Snapchat user. In most cases, you'll want to send additional user traits and [Snapchat parameters](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#user-data-parameters) to improve the number of the events that are matched to a Snapchat user. See [Snapchat's documentation](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters) on all of the parameters that Snapchat Conversions API accepts.

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

Snapchat also requires a number of normalization rules. The Freshpaint integration will automatically normalize most user data fields according to Snapchat's requirements. For more details, see the Snapchat API documentation linked above.

<table data-full-width="true"><thead><tr><th>Freshpaint property</th><th>Snapchat parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>madid</code></td><td><code>madid</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td></td></tr><tr><td><code>email</code></td><td><code>em</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>The email of the user.</td></tr><tr><td><code>phone</code></td><td><code>ph</code></td><td>string</td><td><mark style="color:$success;">Recommended</mark></td><td>The phone number of the user.</td></tr><tr><td><code>first_name</code></td><td><code>fn</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>First name of the user.</td></tr><tr><td><code>last_name</code></td><td><code>ln</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Last name of the user.</td></tr><tr><td><code>gender</code></td><td><code>ge</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Gender of the user. Snapchat only accepts <code>mf</code> or <code>f</code>.</td></tr><tr><td><code>city</code></td><td><code>ct</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's city.</td></tr><tr><td><code>state</code></td><td><code>st</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's state.</td></tr><tr><td><code>zip</code></td><td><code>zp</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's zip or postal code.</td></tr><tr><td><code>country</code></td><td><code>country</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The user's country.</td></tr><tr><td><code>external_id</code></td><td><code>external_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>A unique ID such as a loyalty card ID, first party cookie identifier, or some other identifier.</td></tr><tr><td><code>sc_cookie1</code></td><td><code>sc_cookie1</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>If you are using the Pixel SDK, you can access a 1st party cookie by looking at the _scid value under your domain. Will increase your user match rate.</td></tr></tbody></table>

#### Hashed Fields

Snapchat expects the following fields to be hashed when sent to them. **You should not hash these values** when sending to Freshpaint. The Freshpaint integration will automatically normalize the real, readable values and then hash them before sending them to Snapchat.

{% hint style="warning" %}
If you are a HIPAA customer, it's important to understand that even though the user information is hashed before being sent to Snapchat, HHS guidance still considers this PII since it does not use a secret. Therefore, you must be extremely careful to avoid sending health data alongside this user information to avoid a HIPAA violation.
{% endhint %}

* `email`
* `phone`
* `first_name`
* `last_name`
* `gender`
* `city`
* `state`
* `zip`
* `country`
* `external_id`

### App Data 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>advertiser_tracking_enabled</code></td><td><code>advertiser_tracking_enabled</code></td><td>int</td><td><mark style="color:$info;">Optional</mark></td><td>Set it to 1 or 0 to indicate an OPT_IN or OPT_OUT respectively for MOBILE_APP events.</td></tr><tr><td><code>extinfo</code></td><td><code>extinfo</code></td><td>Array of strings</td><td><mark style="color:$info;">Optional</mark></td><td>Device object from app event. This parameter expects an array with comma separated values. See <a href="https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#extinfo">the Snapchat documentation</a> for more details on this property.</td></tr><tr><td><code>app_id</code></td><td><code>app_id</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>The unique ID (app_id) assigned for a given application.</td></tr></tbody></table>

### Custom Data Properties

The `custom_data` object can contain parameters for [Dynamic Ads](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#dynamic-ads-parameters) and [Dynamic Travel Ads](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#dynamic-travel-ads-parameters), along with any other custom parameters.

<table data-full-width="true"><thead><tr><th>Freshpaint property</th><th>Snapchat parameter</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>custom_fields</code></td><td><code>custom_fields</code></td><td>Object (string : string)</td><td><mark style="color:$info;">Optional</mark></td><td>Object for additional custom fields.</td></tr><tr><td><code>status</code></td><td><code>status</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Indicates the registration status of the customer. Suggested values to pass include: "new", "returning", or "reactivated."</td></tr><tr><td><code>event_tag</code></td><td><code>event_tag</code></td><td>string</td><td><mark style="color:$info;">Optional</mark></td><td>Custom label for events. Examples: in-store, weekend sales, back-to-school campaign</td></tr></tbody></table>


---

# 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://documentation.freshpaint.io/integrations/destinations/direct-response-ads/snapchat-conversions-api/snapchat-conversions-api-reference.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.