Spotify Conversions API Reference

The Spotify Conversions API destination is currently in Early Access. Please contact [email protected] for more information about this integration.

Destination Info

• Supports Track calls

• Supports HIPAA mode

• Refer to this destination as Spotify Conversions API in the Integrations object

• Connection Modes:

	Client-side	Server-side
Web
Mobile
Server

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.

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

Freshpaint property	Spotify parameter	Type	Requirement	Description
spotify_event_name	event_name	string	Required	The Spotify event name to track. *See below chart for all values. 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.
$action_source	action_source	string	Optional	The medium through which the conversion was made. Valid values: "WEB", "OFFLINE", "APP"
opt_out_targeting	opt_out_targeting	boolean	Optional	If true, the event will not be used for retargeting, only for attribution. If this value is not sent, Freshpaint will default to true.
event_source_url	event_source_url	string	Optional	The URL where the event occurred, must start with "http://" or "https://".
$event_id	event_id	string	Required	Unique identifier for the event chosen by the advertiser, used for deduplication. Freshpaint will autofill this value.
$event_time	event_time	long	Required	RFC 3339 timestamp when the event occurred. Must be in the past. Freshpaint will autofill this value if missing.

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	Measures the action of someone viewing a webpage dedicated to a specific product. Best practices: This event code must be installed on every product page that the advertiser is looking to measure.
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.

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.

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.

Freshpaint property	Snapchat parameter	Type	Requirement	Description
$ip	ip_address	string	Recommended	IP address of the customer’s device.
email	hashed_emails	string	Recommended	The email of the user. Note: Freshpaint will send the hashed value to Spotify. You should not hash these values when sending to Freshpaint.
$device_id	device_id	string	Recommended	Raw device id of the customer device.
phone	hashed_phone_number	string	Recommended	The phone number of the user. Note: Freshpaint will send the hashed value to Spotify. You should not hash these values when sending to Freshpaint.
$user_agent	user_agent	string	Optional	The user agent of the browser where the event occurred.
gender	gender	string	Optional	Gender of the user. Snapchat only accepts MALE or FEMALE.
request_ip_address	request_ip_address	string	Optional	The user's IP address when the request was made.
event_ip_address	event_ip_address	string	Optional	The user's IP address when the event occured.
platform_id	platform_id	string	Optional	The ID of the platform.
session_id	session_id	string	Optional	The ID of the user session.
alias_id	alias_id	string	Optional	A unique ID for the alias of the user.
cookie1	cookie1	string	Optional	First party cookie value used for user match rate.
page_id	page_id	string	Optional	The ID of the page.
connection_type	connection_type	string	Optional	The type of connection.
age_group	age_group	string	Optional	The age group of the user.
$spclid	clickID	string	Required for Click Through Conversions	Spotify's click ID, used for attribution of clicks to conversion events.

Event Details Properties

Freshpaint property	Snapchat parameter	Type	Requirement	Description
amount	amount	float64	Required for PURCHASE events	Monetary value of purchase.
currency	currency	string	Required for PURCHASE events	ISO 4217 currency code of purchase (e.g., USD, CAD).
content_name	content_name	string	Optional	Name of the product or page involved in the event.
content_category	content_category	string	Optional	Category of the content, should align with Google's Product Taxonomy.