Localytics API


Audience Exports

Audience Exports allows you to export Audiences created in the Localytics Dashboard for engagement in other platforms.


Localytics empowers marketers to create rich and granular audiences via its industry leading segmentation tools. Our platform then uses the audiences to drive personalized and highly targeted mobile engagement, that positively impacts our customer’s most valuable business KPI’s. Our customers have found tremendous value in this process, however, often times they want to use this segmentation to drive engagement in non-mobile channels like email or online advertising. For example, “create an audience of all users that have made an in-app purchase in the past 7 days, but opted out of push, so that I can automate sending them a customer loyalty email every Wednesday morning”. Audience Exports was built to satisfy this and other similar use cases.

Getting Started

Audience Exports accepts HTTP GET requests authenticated with an API Key/Secret. Every request must include the following information:

  • Authentication - Org level API key and secret that allows Localytics to authenticate your request.
  • Audience information - Audience specific parameters that allows Localytics to properly identify the audience and format the output.

Configuring Audiences for Export

Before making a request to the API you must enable the audience you want to export via the Localytics Dashboard. To enable a given audience for the first time (after creating the audience):

  1. Navigate to the Audiences Screen and find the Audience you want to enable
  2. Click the Action menu and click Enable Audience Export
  3. From the pop-up modal select output type and click Enable

Managing Audience Exports

To disable or re-enable exports you must visit Data Export in the Localytics Dashboard.

Implementation Details

Before integrating, here are some details you need to know:

  • Audiences are refreshed daily starting at 8 a.m. EST and typically finish within an hour.
  • A maximum of 5 audiences, per organization, can be available to the API at a time with an Enterprise Analytics or Enterprise Marketing subscription.
    • A maximum of 20 Audiences, per org, can be available to the API with an Enterprise Remarketing subscription
  • You must first create and enable the audiences in the Localytics Dashboard before attempting to request them via the API.
  • Deleting the audience in the Localytics Dashboard will stop it from refreshing and make it unavailable via the API
    • Audiences not requested in a 45 day period will also stop refreshing and be made unavailable via the API.

Audience Exports Transactions


The base URL for all requests is:



Audience Exports uses Basic Access Authentication. You can use your organization’s API Key/Secret to authenticate the request. These are the same credentials you use to authenticate requests to the Localytics Profile API, Push API, and Events API.

You can find your organization’s API Key/Secret by navigating to the API Keys section of the Account page in the Localytics Dashboard.

Rate Limits

Audience Exports enforces the following rate limits per API Key:

  • 50 requests per minute.

Audience Request Parameters

Authentication Parameters

Parameter Required? Description
api_key Required This is the customer key assigned by Localytics. Your key can be found here

Example: 7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee
api_secret Required This is the customer secret assigned by Localytics. Your key can be found here

Example: 19c2aac0000a23803e9676a-97b8814a-75f4-11e6-bf23-008d99911b00

Audience Parameters

Parameter Required? Description
audience_id Required This is a Localytics-generated identifier for the audience being requested. It is unique to a given audience. The audience_id will be formatted as a positive integer.

This can be found beside the Audience name in the enablement modal or in Data Exports

Example: 153829
identifier_type Required This is the type of identifier that Audience Exports will return — for example, Apple Identifier for Advertising (IDFA) or Localytics Customer ID.

The identifier_type value should be one of the following:
Identifier Identifier_type
Apple Identifier for Advertising (IDFA) idfa
Google Advertising ID (GAID) gaid
Email Address email
Customer ID customer_id


Here is an example with IDFA as the identifier type.

curl -L https://[api_key]:[api_secret]@api.localytics.com/v1/exports/audiences/153829/idfa


Audience Exports will return a 302 response code with a location header pointing to a file containing the results, if your request is formatted correctly.

Example Response

  HTTP/1.1 302 Found
  Date: Wed, 30 Nov 2016 14:47:38 GMT
  Content-Length: 0
  Connection: keep-alive
  Location: https://auditorium-cache-prodprimary.s3.amazonaws.com/queries/fae3e6102993ef78d079ca16688ecdea35d5dfe2273986c1fafb500ea3ab012e-v1/c14ffba3-bfe2-4e5c-a16b-cd1f6850c5dd?AWSAccessKeyId=AKIAIT2WF7LISGBN23SQ&Expires=1480689996&Signature=0e6QA2ec8wEf%2FxAo6iYM47RinYk%3D

Redirect Output

The redirect output will be a JSON formatted file where each row contains an identifier, however, the file will not contain a header row. For example:


Requesting a List of Available Audiences


The base URL is:



An Audience list request will result in a JSON formatted response with the following information:

Parameter Required? Description
id Required The identifier of the export job.
source_type Required The object being exported (ex. audience).
source_id Required The identifier of the object being exported.
job_type Required The type of data being exported (ex. idfa).
results_generated_at Optional The last time the results for this export were generated. If missing no results have been generated yet.
last_requested_at Optional The last time the result for this export were requested. If they have never been requested this value will be missing.

Sample Response

    "id": 6,
    "source_type": "audiences",
    "source_id": "45644",
    "job_type": "idfa",
    "last_requested_at": "2017-02-13T14:30:47Z",
    "results_generated_at": "2017-02-13T12:30:43Z"
    "id": 7,
    "source_type": "audiences",
    "source_id": "4478",
    "job_type": "email",
    "results_generated_at": "2017-02-13T12:30:48Z"

HTTP Response Codes

Audience Exports return the following HTTP response codes:

Code Description
302 The audience request was successful and Localytics will redirect the requestor to a file containing the export.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not match with a Localytics Org or the Org doesn’t have access to the specified audience.
404 The source type is unknown. Remember, it should always be “audience” when using Audience Exports.
429 You’ve met your 10 request per minute limitation and are now being throttled.

Version History

Version Date Change Summary
0.5 01/18/2017 Beta release version.
1.0 04/06/2017 GA release version. Includes self-serve Dashboard management, audience list request functionality, and new URL structure.

Profile Exports

Profile Exports allows you to export, in bulk, preferences and behaviors of users associated with your app for engagement and analysis in other platforms.

Coming soon!

Log Exports

Log Exports allows you to export your raw Localytics data for deeper analysis using legacy business intelligence or internal tools and systems.

Coming soon!


Profile Imports

Profile Imports allows you to import and/or update Localytics' Profiles with data about your users from other systems.

Coming soon!

Audience Imports

Audience Imports allows you to import a list of users from your internal tools and systems for engagement in the Localytics Platform.

Coming soon!