Liftoff API for Audiences Integration

For partners working on behalf of multiple clients.

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.

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