1

Server to Server Technical Specs - Outbound from Lotame - Real-Time API

A common industry practice to activate audience data in real-time is through pixel drops on a user's browser. However, potential restrictions on the number of pixels fired and possible network latency resulting in aborted drops make this an inefficient mechanism to activate audience data to some Lotame partners. Lotame's real-time S2S integration capability circumvents these issues by directly sending audience data to your system, thus reducing delays and avoiding the limitations of relying on a browser to activate data.

Data Delivery Endpoint

To be able to ingest the audience data being activated, you will need to provide a URL to Lotame. Lotame will deliver the audience data on a user to this URL as explained below.

Data Format

The data is activated via POST requests containing a JSON payload. Currently each payload will contain the audience list for a single userId. In other words, Lotame will send one JSON payload, per user, containing all the audiences that the user belongs to.

JSON Body Spec

Key Data Type Description
deliveryTime Number UNIX timestamp of when packet was delivered
users Array of Objects Array containing a single Json Object with a userID and an array of audiences
userID String Unique identifier for the user being activated
audiences Array of Numbers Array containing Lotame audience IDs for all the audiences that the user belongs to
deviceType String Optional. Will include the device type for the userId value. The deviceType will use the 'Identifer Prefix' listed in the 'Supported userId section' below.

Example JSON Body

This shows a userID being associated with 3 different Audiences.

{
  "deliveryTime": 1312312323,
  "users": [{
    "userID": "C87CB4B6-87A1-42E3-A994-B3734A0D4F69",
    "audiences": [111111,22222,333333],
    "deviceType": "IDFA"
  }]
}

Supported deviceType Identifiers

Universal IDs
Identifier Prefix Description
PANO Lotame Panorama ID  ™
Web IDs
Identifier Prefix Description
{deviceType not sent} Lotame Profile IDs (pid)
{deviceType not sent} Third Party IDs (tpid)
Mobile IDs
Identifier Prefix Description
IDFA Apple Identifier for Advertising
GAID Google Advertising ID
Connected TV IDs (OTT) IDs
Identifier Prefix Description
RIDA Roku TV and Streaming Devices
TVOS Apple TV
CHRM Android TV / Google Chromecast Devices
AFIA Amazon Fire TV Devices
SMSG Samsung TVs

To see our full list of supported CTV IDs, please see our CTV Overview page.

Data Transmission

Whenever a user is qualified into an audience, or is removed from an audience, a message will be sent to your API endpoint provided above. This is a comprehensive list meaning if when last sent there were 2 audiences and the device is removed from one, Lotame will re-send the device with only one audience.

There are only 2 acceptable response codes. 200 for success with an empty body and 500 for any errors with an object explaining the error.

Please note that the error response will be used for logging and debugging purposes only. Lotame system will neither automatically react to the error message nor perform any sort of retry.

Any response not 200 or 500 will be ignored by the Lotame system.

Error Return Object Format

Main Object

Use the error in the main object for generic errors not related to the data in the request. Use the usersInError object for data related errors.

Key Data Type Description
error String Brief description of error encountered. Used for generic errors.

Maximum length of the string is 100 characters. Any characters exceeding this length will be truncated
usersInError Array of Objects Array of objects whose definition is in the following table.

These above two fields should not be included at the same time and if there are, only error is processed.

usersInError Object

The usersInError object is an array of objects with each object having the following parameters. Passing usersInError allows you to provide specific details to an individual user that you failed to load on the request.

Key Data Type Description
userID String Unique identifier for the user being activated
errorDetails String Brief description of error encountered for this specific user.

Maximum length of the string is 100 characters. Any characters exceeding this length will be truncated.

Example Error Responses

Unable to Process Packet

If for some reason the packet could not be processed at all (malformed, etc), respond with a 500 response code and a generic error message as follows:

{
  "error": "Brief description of error encountered"
}

Unable to Process UserID Data

If the userID in the packet could not be processed, respond with a 500 response code and the userid and a specific error inside the usersInError object. 

{
  "usersInError": [{
    "userID": "60773733b1f258e9ac24d666dee1463a",
    "errorDetails": "UNKNOWN_ID"
  }]
}
Upvote1 Follow
  • 1 Upvotes
  • 8 days agoLast active
  • 135Views
  • 1 Following
Log In