LiveIntent logo
API docs by Redocly

Audience API (1.0.0)

LiveIntent Support: support@liveintent.com

Introduction

The Audience API helps LiveIntent partners to programmatically exchange data for creating and managing audiences. The API enables a high level of automation, which helps LiveIntent partners increase efficiency, reduce labor requirements, and improve audience delivery time.

As a LiveIntent partner, you can leverage the Audience API to create and manage Custom Audience. This API supports the HTTP GET, POST, and PATCH methods. The following sections describe how to call the endpoints.

Authentication

The LiveIntent Audience API utilizes access tokens for request authentication. These access tokens grant you the necessary privileges to access the Audience API endpoints, allowing LiveIntent to identify the sender of a request and verify their access rights.

To get an access token, contact your account team at LiveIntent. Then use the provided access token as a bearer token in the Authorization header when sending request to any of the endpoints.

What is a Custom Audience?

The Audience API currently supports creation and management of Custom Audiences. A Custom Audience lets you upload first-party data (either emails or mobile identifiers) that you wish to target or suppress across LiveIntent’s ad exchange. Email identifiers can be hashed or unhashed. For more information on Custom Audiences, please visit our Knowledge Base.

The Audience API offers a collection of endpoints for accessing and maintaining your Custom Audiences. The API reference section of this document describes the elements of each endpoint.

Identifiers supported by Custom Audiences

A Custom Audience may contain three different types of identifiers which are as follows.

Id type Description
EMAIL_HASH Use when uploading MD5, SHA-1, SHA-2, and unhashed emails
AAID Google advertising identifier for Android devices
IDFA Apple identifier for advertisers

Setting up a Custom Audience

To set up a functional Custom Audience, perform the steps below.

  1. Create an audience. See the API reference section for Create Audience.
  2. Obtain a signed URL for upload. See the API reference section for Generate signed URL.
  3. Upload first-party data (user identifiers) to the signed URL.

Preparing an audience upload file

Typically, you will create your Custom Audience and then add a list of customers that you wish to target or suppress. Use this guide when preparing the audience file. The information here can also be helpful for troubleshooting issues with audience files.

Formatting audience file

Consider the following guidelines when preparing your audience file for upload.

  • Create a .txt, .csv, or .zip file containing a single column. No other file format is supported.
  • Make sure that each row in the file contains a single identifier.
  • Do not use column name or other text. Start the first row with the first identifier.
  • Include identifiers of the same type (email hash or MAID) in a file.
  • Use only one identifier per line.
  • Do not use uppercase letters.
  • Do not use salted hashes.
  • Do not use extra spaces or special characters.
  • Do not use spaces before or after an identifier.

Examples

The following file excerpt is an example of correctly formatted email hashes:

D5f0726215cdf6d9dbf7f5fa43c47850
A1568e8c0d8faff3fc0ec7d612531189
F0754457d38013a31be0766eb1d97e0c
J5e1043d20ce435f9c54b6a202ed299c

The following file excerpt is an example of incorrectly formatted email hashes that include spaces and more than one hash on a line:

D5f0726215cdf6d9dbf7f5fa43c47850 A1568e8c0d8faff3fc0ec7d612531189
F0754457d38013a31be0766eb1d97e0c
J5e1043 d20ce435f9 c54b6a202ed299c

Troubleshooting audience files

If you upload email hashes, please make sure each hash conform to the following standard character length:

  • MD5 hash is 32 characters.
  • SHA-1 hash is 40 characters.
  • SHA-256 hash is 64 characters.

There are no limits to the number of identifiers that you can send in a single file upload. However, we recommend that you keep your upload file moderately large.

If you are unable to successfully upload your audience files, and have confirmed the file follows the formatting guidelines,, please reach out to your LiveIntent team.

Using a pre-signed URL

The information in this section will help you successfully initiate an audience file upload.

Follow the steps in this guide to successfully upload your audience file.

  1. Start by getting your audience file ready. See Preparing audience upload file. The supported file formats are text/csv, text/plain, application/zip.

  2. Before you upload a file, get a signed URL. The signed URL is a string granted as time-limited permission for making a request. The signed URL contains authenticated information in its query string and gives you the right access to perform specific upload actions. To obtain the right access for the operation you are trying to perform, specify the appropriate value for the action parameter when generating a signed URL.

The following table describes the supported file upload actions.

Action Description
ADD Adds identifiers to a specified audienceId.
REMOVE Removes identifiers from a specified audienceId.
REPLACE Replaces all identifiers of a specified audienceId with the content of an upload file.
  1. After you have obtained a signed URL, upload your data by using the signed URL together with the content of your audience file. The URL can be used to make only one upload and it is valid for 30 minutes. It is required to add the content type of the file to the request!

The following is an example cURL request showing the pre-signed URL with data in the request’s body:

curl --request PUT --url "https://raw-audience-uploads.s3.amazonaws.com/upload/2021-01-13/123456/add/96c483ba6b1234549f9b6854606c4d9d/353cee92-172d-44b6-ac56-2f4cab34371a?x-amz-meta-type=email-hash&x-amz-meta-segment-id=166997&x-amz-meta-unique-segment-id=166997&x-amz-meta-action=add&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEN%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc6QtMSJHMEUCIDFy8qyHu0V8%2BazVtqaW1GtWHt9C9VJa%2B5By1ZTKTLz7AiEAjpDiimeHkIh67bUFLMw34JfrtiSPXEzo6Iye6hMzL2Mq%2BgMIFxAAGgw0MjU5Mz756RHlkCBqZci49QZ77eri9Rw2lPpmZgFz5VGWkrydBDBujet2%2Bg1B16w75hO9DCFsQOw%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210113T142421Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=ASIAWGK5HWMJGBBHLOWB%2F20210823%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=d07c43827c5599625dd13ad45ebed3b264f4447cf14ab3711ab0c4ac607cca07" 
--data "d8e8fca2dc0f896fd7cb4cb0031ba249" -H "Content-Type: text/csv"

The following is an example cURL request showing the pre-signed URL with file upload:

curl --request PUT --url "https://raw-audience-uploads-staging.s3.amazonaws.com/upload/2021-12-20/167192/add/84a72f3a33014f39a39a079ae9bffea1/test_signed2?x-amz-meta-type=email-hash&x-amz-meta-segment-id=167192&x-amz-meta-unique-segment-id=167192&x-amz-meta-action=add&X-Amz-Security-Token=FwoGZXIvYXdzEBcaDFXeN%2BOHzkbW1fYg3SKtAeqASMxIILTzy9SFP5bNQcUyc0WPBg%2FEetiwdR6nZRLa9IyiTvSTmk2VNReNjdpR2EYap5gIuIgnoCLSxEFpbQv7MDFGvE6oYLiJWFoSHvcOeNWg6L3zLhgk1NTHtRbsMtlHud7BqUNvCw5ybBirRnNALKnb0hUAl5r3B3uz%2FjrB6IENx9S1AVJTY%2BNoAZak%2B1dScw8XCgh9GFkFPKUtO0yDcUyxziq2HZTWGGGyKOmZgo4GMi02j4Noc3o2iuWWz6x4n3CjgURoJqW3bw7JdAQHAN6ngmZtjDTAPWuT%2FkdthAc%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20211220T143929Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAWGK5HWMJJQPTEGWW%2F20211220%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=895ea80bcf5399e7e492df64177102e4bb321f6df75f8495f238681318677f39" \
-T identifiers.zip -H "Content-Type: application/zip"

Create audience

This endpoint lets you create an audience for a specified accountId. The operation returns an identifier of a newly created audience.

Create Custom Audience

This resource lets you create a Custom Audience. It takes in only the request body in JSON format (no query parameters).

Authorizations:
BearerToken
Request Body schema: application/json
required
dataProviderId
required
integer <int64>
Enum: 84 101
name
required
string
accountId
required
integer <int64>

Specify your LiveIntent account identifier.

object

Responses

Request samples

Content type
application/json
{
  • "dataProviderId": 84,
  • "name": "string",
  • "accountId": 0,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "accountId": 0,
  • "dataProviderId": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "metadata": {
    }
}

Update/modify audience

Use this set of resources to update or modify your audience information.

Modify audience name

Use this resource to update an audience name.

Authorizations:
BearerToken
path Parameters
audienceId
required
integer <int64> (AudienceId)

Specify an audience you would like to modify its name.

Request Body schema: application/json
required
name
string

Assign a new name to the specified audienceId.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "accountId": 0,
  • "dataProviderId": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "metadata": {
    }
}

Generate signed URL

This endpoint lets you generate a signed URL that provides permission for modifying the members of an audience by uploading a file containing common types of user identifiers. See the Using a pre-signed URL guide for details of how to proceed after obtaining a signed URL. The operation returns an optional processing report to the notificationEmail address you provide.

Authorizations:
BearerToken
path Parameters
audienceId
required
integer <int64> (AudienceId)

The identifier of the audience to which you are uploading the user identifiers.

Request Body schema: application/json
required
uploadName
string

Name of the file you want to send to a signed URL. The file name will be used as a key when the content is stored. If not specified, a random name will be generated.

notificationEmail
string

Assign an email address for receiving the processing report once the file processing has completed.

identifierType
required
string
Enum: "EMAIL_HASH" "AAID" "IDFA"

The type of user identifier. Specify the type of user identifier you would like to upload.

action
required
string
Enum: "ADD" "REMOVE" "REPLACE"

Specify the action type to be performed on a given audienceId, in terms of whether the identifiers in the file be added or removed from an audience or entirely replace the audience.

Responses

Request samples

Content type
application/json
{
  • "uploadName": "string",
  • "notificationEmail": "string",
  • "identifierType": "EMAIL_HASH",
  • "action": "ADD"
}

Response samples

Content type
application/json
{
  • "signedUrl": "string"
}

Query audience

Use this set of resources to query the system for information about your audiences.

Get information for all audiences

This resource lets you query the endpoint for all the audiences in an account. The operation returns descriptive information about each audience.

Authorizations:
BearerToken
query Parameters
pageSize
integer >= 0
Default: 30

The number of records per page. Use if you expect large response data.

page
required
integer >= 1

Specify the maximum number of page to be returned.

updatedAfter
string <date-time>

Only return audiences that were updated after this point in time. This should be an ISO 8601 date string in UTC (Zulu) time zone.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "totalCount": 0
}

Get specific audience information

This resource lets you query the endpoint for information about a specific audience in an account.

Authorizations:
BearerToken
path Parameters
audienceId
required
integer <int64> (AudienceId)

Specify the audience identifier for which you are requesting information.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "accountId": 0,
  • "dataProviderId": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "metadata": {
    }
}

Get audience counts

Use this resource to obtain the number of active identifiers (match) and the total number of identifiers (total) that belong to the specified audienceId.

Authorizations:
BearerToken
path Parameters
audienceId
required
integer <int64> (AudienceId)

Specify the audience identifier for which you are requesting count information.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

Get file upload history

Use this endpoint to get file upload information by passing in the corresponding audienceId. The endpoint returns a history of the file upload that has been previously uploaded to the specified audienceId.

Authorizations:
BearerToken
path Parameters
audienceId
required
integer <int64> (AudienceId)

Specify the audience identifier for which you are requesting file upload history.

query Parameters
pageSize
integer >= 0
Default: 30

The number of records per page. Use if you expect large response data.

page
required
integer >= 1

Specify the maximum number of page to be returned.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "totalCount": 0
}

Search audiences

Use this endpoint to retrieve audiences using a more sophisticated filter.

Authorizations:
BearerToken
query Parameters
accountId
integer <int64> (AccountId)

The LiveIntent account identifier.

Request Body schema: application/json
required
pageSize
integer >= 0
Default: 30

The number of records per page. Use if you expect large response data.

page
integer >= 1

The page that should be returned.

includeInternal
boolean

Whether to inlude internal audiences.

object or object or object or object or object or object or object

Which audiences to include in the response.

Responses

Request samples

Content type
application/json
Example

Search for audiences that have a DataProvider with id 95 and metadata with the key bar. Show the second page with 15 elements.

{
  • "page": 2,
  • "pageSize": 15,
  • "matches": {
    }
}

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "totalCount": 0
}