LiveIntent Conversions API

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. Getting 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 and customer ID to use Conversions API.

Using the API

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

API call example for an event on a web page:

curl -X POST \
  -F 'data=[
       {
         "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
         "pixelId": 44489,
         "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"
       }
     ]' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 https://conversions.liveintent.com/{CUSTOMER_ID} 

API call example for an event in a mobile application:

curl -X POST \
  -F 'data=[
       {
         "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
         "pixelId": 44489,
         "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"
       }
     ]' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  https://conversions.liveintent.com/{CUSTOMER_ID}

API call example for an event that happened offline:

curl -X POST \
  -F 'data=[
       {
         "eventId": "3b27d254-79b7-4615-b5a5-b918c0432e83",
         "pixelId": 44489,
         "eventTime": 1723193288,
         "source": "offline"
         "userData": {
           "sha2": "936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af",
           "md5" : "29a1df4646cb3417c19994a59a3e022a"
         },
         "purchaseData": {
           "currency": "USD",
           "value": 123.45,
       }
     ]' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  https://conversions.liveintent.com/{CUSTOMER_ID} 

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: jondoe@gmail.com

• MD5: 29a1df4646cb3417c19994a59a3e022a

• SHA256: 2236ef1127a87fd2dc91e63ddc1038c45843a0c1c07440df59aa09448bb1494c

API Response

Success

In case of success, LiveIntent Conversions API returns an HTTP response with code 200 along with an empty body. This means that all the supplied events were processed successfully.

Partial success

There is a possibility that the request is valid, but LiveIntent Conversions API did not process all or some of the events supplied. In this case, API responds with code 200 and a response body that lists all the event_ids that need to be resent.

Example of the response body:

{“failed”: [
  “3b27d254-79b7-4615-b5a5-b918c0432e83”, 
  “2768d254-79b7-4615-b5a5-b918c0786124” 
]}

Next Steps: Resend all the event_ids from the response body.

Authorization error

If the authorization token was not provided the API will respond with 401 HTTP error code. If it was provided but it is invalid, Conversions API will return a 403 HTTP error code with empty body.

Next Steps: Reach out to your Account Manager for an authorization token. When you get a valid token, resend all the batches.

Malformed input

When malformed data is supplied, Conversions API responds with 400 HTTP code along with JSON body.

JSON will contain information about incorrect data provided in the message in the format

[index-of-invalid-value].path-to-invalid-field(error-message).

Example of the response body:

{
  “httpStatus”: 400,
  “message”: “[0](Either aaid or idfa must be defined for mobile apps, AppBundle must be defined for mobile apps), [1].clientEventId(missing)”
}

Next Steps: Validate the format of the supplied data and use error messages as a guidance. Once that’s complete resend the whole batch.

Server errors

Conversion API can also return a 500 HTTP response code in case something is wrong on the server side.

Next Steps: Resend data.

API Specification

This paragraph lists all required event data parameters and any additional data parameters the LiveIntent Conversions API needs to use for ads delivery optimization and/or conversions attribution.

Object: Data

Object: Event

Object: User Data

Object: Purchase Data

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.