Conversion API

12 min

overview the conversion api version 1 0 allows publishers using the platform to share data with aperture directly from their servers or from third party event aggregators like mobile app data providers, location based conversion data services, and others this api provides you with deeper funnel visibility and enhanced data control it unlocks new ways for dsp clients to optimize performance campaigns based on their own first party conversion data the cadent platform supports the ability to send various types of events, such as page views, purchases, and registrations so that you can collect these conversion events as common building blocks for targeting, measurement, and campaign optimization the api supports low latency and real time transmission of events and conversions to the api endpoint through an http protocol the api and its related data pipeline provide error reporting and logging capabilities to track and diagnose issues with api requests note throughout this document, elements that appear inside {} are variables the actual values are unique to your organization and will be provided benefits deeper funnel visibility the conversion api enables the sharing of a wider array of data providing advertisers with more comprehensive information for decision making data control with the conversion api, advertisers have added control over the data they share they can choose to append insights to their events like product margins or historical information signal reliability and resiliency the conversion api offers more reliable data sharing compared to browser based methods it is designed to be less susceptible to issues like browser crashes or connectivity problems ensuring reliable data transmission setting up the conversion api before sending conversion api transactions to aperture, use the create datasets feature in audience to create a specific conversion api dataset the new dataset becomes the container for the data you send over the api for instructions on creating datasets, see the aperture online help note the array structure for the transactions allows you to send a maximum of 1,000 events in each transaction when creating the dataset, at ingestion source , you must select conversion api make note of the dataset id on the dataset details page hashing requirements and personally identifiable information the api supports hashing of customer information parameters and match keys that personally identify individuals, such as names, email addresses, and phone numbers these parameters should be used for matching purposes only and are not available for use in the audience studio application, or through destinations, or other downstream processes no customer personal identifiable information (pii) will be available as a result of this api customer information is used for matching purposes only hashing is supported for the following fields did ip zip11 email endpoint https //events cadent tv/v1/datasets/{datasetid}/conversions endpoint details {datasetid} this auto generated, numeric id displays on the dataset details page for a dataset access the dataset details page by clicking a dataset's row on the datasets page http supported method post api key in header x api key {apikey} you will receive a unique {apikey} value from cadent for security reasons, these keys may be set to expire in the future if that happens, you will receive a new key from cadent payload format json cadent api gateway performs two primary functions it secures exposed external api’s using the api key authentication it routes external api requests to internal services endpoint conversion api request processing workflow you can leverage the conversion api to send multiple event types server events are linked to a dataset id and are processed in the same way as events the end point is exposed through google cloud using an http post method \[ { "event name" "purchase"' "event time" 1707282271, "currency" "usd" "sales amount" 16 00" "lifetime value" "16 00", "store id" "tx2006", "item number" "1" "dma code "231" "postal code" 11249", "user data" { "em" "309a0a5c3e211326ae75ca18196d301a9bdb1a882a4d2569511033 da23foabc" } } request payload for the http service the payload transaction that you send is organized in an array structure this section defines the fields included in the payload, indicates which are required, and provides a payload example supported array parameters \name\ \definition\ conversion type derived from specified value in the dataset form, so this cannot be set per event the following are the valid values email clickthrough — click through event through email site clickthrough — event is triggered whenever a site visitor clicks a link in a site page or display ad online purchase — conversion event based on online purchase app install — conversion was based on mobile app install in app purchase — conversion was based on mobile in app purchase physical store visit — conversion event based on store visitation offline purchase— conversion event based on offline/in store purchase phone call — lead generation event by phone chat event — conversion event was made via a messaging app, sms, or online messaging feature system generated — conversion happened automatically, for example, a subscription renewal that’s set to auto pay each month other — conversion happened in a way that is not listed event name the name for the conversion file the limit is 64 characters event type unix timestamp in seconds indicating when the event occurred data is stored in utc format currency the three letter iso currency code sales amount value of the conversion event lifetime value lifetime value of a conversion event must be listed as a currency value store id a unique alphanumeric identifier for each location for retail and offline sales data order id a unique alphanumeric identifier for each transaction or order in a conversion dataset maximum of 64 characters for example, for retail this may be a receipt id item number a unique identifier to distinguish events within the same order or transaction dma code a 3 digit designated market area where the transaction took place postal code a 5 digit zip code where the transaction took place this postal code is not related to the zipcode for the match key it is not related to the home address of the household but is used to capture a store location user data \name\ \data type\ \definition\ em string or list\<string> the email of the person associated with the impression this value can be encrypted hashing required client ip address string or list\<string> the ip address of the browser corresponding to an event must be a valid ipv4 or ipv6 address do not include spaces always provide the real ip address to ensure accurate event reporting madid string or list\<string> user mobile advertiser id the advertiserid from an android device or the advertising identifier (idfa) from an apple device this parameter is for app events only crosswalk id string or list\<string> this is the usps postal address in the format of address1, address2, city, state, zip address1, address2, city, state, zip string or list\<string> this is the usps postal address in the format of address1, address2, city, state, zip fn string or list\<string> first name, alphabet characters lowercase only with no punctuation if using special characters, the text must be encoded in utf 8 format hashing required in string or list\<string> last name, alphabet characters lowercase only with no punctuation if using special characters, the text must be encoded in utf 8 format hashing required db string or list\<string> date of birth in yyyymmdd format hashing required ge string or list\<string> gender single initial in lowercase for example, m or f hashing required ct string or list\<string> city alphabet characters, lowercase only with no punctuation, no special characters, and no spaces if using special characters, the text must be encoded in utf 8 format hashing required st string or list\<string> state two character ansi abbreviation code in lowercase do not use punctuation, special characters, or spaces hashing required zp string or list\<string> zip code enter the first 5 characters of the u s zip code use the area, district, and sector format for the uk hashing required country string or list\<string> country enter the iso 3166 1 alpha 2 lowercase 2 character country code hashing required external id string or list\<string> any unique id from the advertiser, such as loyalty membership ids, user ids, and external cookie ids you can send one or more external ids for a given event hashing recommended client ip address string the ip address of the browser corresponding to an event must be a valid ipv4 or ipv6 address do not include spaces always provide the real ip address to ensure accurate event reporting do not hash client user agent string the user agent for the browser corresponding to the event the client user agent is required for website events shared using the conversion api you are encouraged to send both the client ip address and client user agent parameters through the conversion api for all events to improve event matching and ad delivery for dsp campaigns do not hash subscription id string the subscription id for the user in this transaction; it is similar to the order id for an individual product do not hash anon id string user install id this field represents unique application installation instances this parameter is for app events only do not hash madid string user mobile advertiser id the advertising id from an android or apple device this parameter is for app events only do not hash success message the following message indicates that the transaction request was received successfully { "success" true } error response the following message indicates an error in request transaction file { "success" false, "requestid" "someid", "reasoncode" "httperrorcode", "reasondesc" "error message" } error messages the following are issues and their accompanying messages that indicate problems with api transactions status code http bad method only http post method is supported status code http unsupported type content type application/json status code http bad request or message dsid and groupid and apiversion required dsid is a required parameter status code http bad request or message dsid and groupid and apiversion required groupid is a required parameter status code http bad request or message dsid and groupid and apiversion required apiversion is a required parameter status code http bad request or message entityid and groupid not matching entity id is a required parameter in the header status code http bad request or message entityid and groupid not matching entity id is a required parameter in header dataset is not present for group validate dataset id belongs to the specified groupid no validation in google cloud function this is validated on data flow side event time is not valid no validation only 1000 events are allowed at a time the system cannot validate more than 1000 events at a time