Skip to main content

API Audience Integrations

April Tam
Updated

Overview

The Liftoff Audiences API lets you create and manage audience segments programmatically. It’s designed for partners working on behalf of multiple clients who need to automate audience creation, updates, and suppression at scale.

For simpler batch uploads of suppression lists and audiences via flat file, see the S3 Audience Integrations page.

Getting started

Contact your Account Manager to request API credentials. You’ll receive a customer-level Liftoff API key and a partner-level set of HTTP Basic Authentication credentials, provided via a separate channel.

API endpoint

All requests should be sent via the following endpoint, where {action} is the identifier for one of the associated audience builder actions described below:

https://analytics.liftoff.io/audiences/v1/{partnername}/{action}

Authentication

Customers are identified via their Liftoff API key. You can use the validate action to verify if they have provided a legitimate API key. Additionally, you will be provided with a partner-level set of credentials to use for HTTP Basic Authentication that will need to be provided with all API calls.

API credentials will be provided via a separate channel. Replace user:secret with your username and password in the examples below.

Supported actions

validate

Used to verify the validity of a Liftoff API key. Supports GET requests with an api_key parameter in the query string or POST requests with an api_key parameter in the JSON request body.

Sample responses

Status code Sample response
200 {"success":true}
401 {"success":false,"error":"invalid API key"}

Examples

curl --user user:secret \ https://analytics.liftoff.io/audiences/v1/{partnername}/validate?api_key=123456789

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789"}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/validate

create

Used to create a new audience. Audience names must be unique per customer/platform.

Request body parameters

Parameter Description
api_key Customer’s Liftoff API key
name Desired audience name
platform (Optional) Platform for devices stored in this audience: "android" or "ios"

Sample responses

Status Code Sample Response
200 {"success":true,"audience_id":432}
401 {"success":false,"error":"invalid API key"}
409 {"success":false,"error":"audience with name 'sample' already exists"}

Examples

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789","name":"sample"}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/create

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789","name":"new users"}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/create

delete

Used to delete/inactivate an existing audience. The actual inactivation happens downstream, so a successful response only indicates that the deletion request was accepted.

You should limit each call to this endpoint to contain at most 15,000 IDs. If you need to add more device IDs than that, you should make additional calls until all device IDs have been sent.

Request body parameters

Parameter Description
api_key Customer’s Liftoff API key
audience_id Audience ID to delete/inactivate

Sample responses

Status Code Sample response
202 {"success":true}
400 {"success":false,"error":"missing or invalid audience ID"}
401 {"success":false,"error":"invalid API key"}
404 {"success":false,"error":"could not find audience"}

Examples

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789","audience_id":432}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/delete
 

add / remove

These actions can be used to add/remove devices from an existing audience. The actual adding/removing happens downstream, so a successful response only indicates that the request was accepted.

Request body parameters

Parameter Description
api_key Customer’s Liftoff API key
audience_id Audience ID to add/remove device IDs to/from
ids Array of device IDs to add or remove. Device IDs must conform to platform-specific casing rules.

Device ID casing rules

  • IDFA ⇒ Uppercase: ABCDEF01-2345-6789-ABCD-EF0123456789
  • Google AID ⇒ Lowercase: abcdef01-2345-6789-abcd-ef0123456789

Sample responses

Status code Sample response
202 {"success":true}
400 {"success":false,"error":"missing or invalid audience ID"}
401 {"success":false,"error":"invalid API key"}
403 {"success":false,"error":"audience has been disabled or removed"}
404 {"success":false,"error":"could not find audience"}

Examples

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789","audience_id":432,"ids":["ABCDEF01-2345-6789-ABCD-EF0123456789","abcdef01-2345-6789-abcd-ef0123456789","fedcba01-2345-6789-abcd-ef0123456789"]}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/add

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789","audience_id":432,"ids":["ABCDEF01-2345-6789-ABCD-EF0123456789","abcdef01-2345-6789-abcd-ef0123456789","fedcba01-2345-6789-abcd-ef0123456789"]}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/remove

list

Used to download a list of enabled audiences that you have been granted access to update. Supports GET requests with an api_key parameter in the query string or POST requests with an api_key parameter in the JSON request body.

Sample responses

Status code Sample response
200 {"success":true,"audiences":[{"audience_id":123,"name":"Sample audience - ios","platform":"ios"}]}
401 {"success":false,"error":"invalid API key"}

Examples

curl --user user:secret \ https://analytics.liftoff.io/audiences/v1/{partnername}/list?api_key=123456789

curl --request POST \
  --header "Content-Type: application/json" \
  --user user:secret \
  --data '{"api_key":"123456789"}' \
  https://analytics.liftoff.io/audiences/v1/{partnername}/list
 

Related to

Related articles

Comments

0 comments

Article is closed for comments.