Conversions API (1.0.0)

The Conversions API is designed to establish a connection between an advertiser's marketing data – such as website events, app events, business messaging events, and offline conversions – from their server, website platform, mobile app, or CRM to LiveIntent's systems.

Instead of managing separate connections for each data source, advertisers can use the Conversions API to transmit multiple event types, simplifying their technology stack. For direct integrations, this involves creating a connection between the advertiser's server and LiveIntent's Conversions API endpoint.

Recommended steps

1. Get started – review the list of necessary requirements and the integration specification.
2. Implement API and start sending requests – start making POST requests and learn more about dropped events, batch requests, and event transaction time.
3. Verify your setup – go through the checklist and make sure all requests were accepted by LiveIntent.

Documentation

Getting started

Before you can get started with the implementation, reach out to your Account Manager to get your authorization token, a customer ID and a pixel ID to use Conversions API.

Tokens are rotated occasionally and will need to be updated. Your Business Manager will reach out to you when it's time to rotate your token. Your Customer ID will remain the same.

Using the API

To send new events, make a POST request to Conversion API's /conversions handler, using the following path – https://conversions.liveintent.com/conversions/{CUSTOMER_ID}

API call example for an event on a web page:

curl -vvv --header 'Authorization: Bearer {TOKEN}' \
https://conversions.liveintent.com/conversions/{CUSTOMER_ID} \
--data '[
  {
    "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
    "pixelId": {PIXEL_ID},
    "eventTime": 1723193288,
    "source": "web"
    "userData": {
    "sha2": "936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af",
    "md5": "29a1df4646cb3417c19994a59a3e022a",
    "ip": "123.123.123.123",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
    (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
    },
    "purchaseData": {
    "currency": "USD",
    "value": 123.45,
    "sourceUrl": "http://example.com/product/123"
  }
]'

API call example for an event in a mobile application:

curl -vvv --header 'Authorization: Bearer {TOKEN}' \ 
https://conversions.liveintent.com/conversions/{CUSTOMER_ID} \
--data '[
  {
    "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
    "pixelId": {PIXEL_ID},
    "eventTime": 1723193288,
    "source": "app"
    "userData": {
    "idfa": "28757bwa-bd67-6d1c74bb-ae4d19ab5d34",
    "trackingEnabled" : 1,
    "sha2": "936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af",
    "md5" : "29a1df4646cb3417c19994a59a3e022a",
    "ip": "123.123.123.123"
    },
    "purchaseData": {
    "currency": "USD",
    "value": 123.45,
    "appBundle": "com.example"
  }
]'

API call example for an event that happened offline:

curl -vvv --header 'Authorization: Bearer {TOKEN}' \
https://conversions.liveintent.com/conversions/{CUSTOMER_ID} \
--data '[
  {
    "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
    "pixelId": {PIXEL_ID},
    "eventTime": 1723193288,
    "source": "offline"
    "userData": {
    "sha2": "936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af",
    "md5" : "29a1df4646cb3417c19994a59a3e022a"
    },
    "purchaseData": {
    "currency": "USD",
    "value": 123.45,
  }
]'

Upload time versus event time

The eventTime represents the time of the event transaction. It should be provided as a Unix timestamp in seconds, reflecting when the event actually took place. This timestamp should be earlier than when the event is sent to LiveIntent, to allow for batch processing and server performance optimization.

The eventTime can be up to 7 days prior to when you send the event to LiveIntent. If any eventTime in the data is older than 7 days, the entire request will result in an error, and no events will be processed. For offline and physical store events where the source is offline, transactions should be uploaded within 30 days of the conversion.

Batching

You can send up to 100 events in data. However, for optimal performance, we recommend you send events as soon as they occur and ideally within an hour of the event occurring. If any event sent in a batch is invalid, the entire batch is rejected.

Hashing

E-mail addresses provided in userData.md5 or userData.sha2 should be hashed. Please follow the guidelines below to achieve best attribution results:

• Lower case the email address
• For @gmail email addresses:
  • Remove the dots
  • Remove everything that follows a "+" sign
• Use MD5 hashing (preferred). Alternatively, SHA256 can be used.

Example – John.Doe+office@gmail.com email:

• Lowercase: john.doe+office@gmail.com
• It's a @gmail.com email address, so:
  • Dots removed: johndoe+office@gmail.com
  • Everything that follows a "+" sign removed: johndoe@gmail.com
• MD5: 29a1df4646cb3417c19994a59a3e022a
• SHA256: 2236ef1127a87fd2dc91e63ddc1038c45843a0c1c07440df59aa09448bb1494c

Validation

To ensure the implementation works and is as effective as possible, use the checklist below.

1. Email hashes are properly hashed.
2. Mobile identifiers, IP addresses, and user agents are not hashed.
3. Make sure you read and process API responses and catch errors.
4. Make sure that you respect event time versus send time limitations.
5. Make sure that you respect batching rules.