Localytics API

Export

Audience Exports

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

Introduction

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

Endpoint

The base URL for all requests is:

https://api.localytics.com/v1/exports/audiences/:audience_id/:identifier_type

Authentication

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

Example

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

Response

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:

  {"IDFA":"E751D492-9BB5-4A6E-B7CA-B0DF980F63FA"}
  {"IDFA":"AF83D440-A7AF-4504-A77C-62FE2FCEF661"}
  {"IDFA":"33882069-6ABE-4ACF-8FA0-41F3DA418560"}
  {"IDFA":"975BD354-D3B8-4DFE-9036-E3ECFCA5B57F"}
  …

Requesting a List of Available Audiences

Endpoint

The base URL is:

https://api.localytics.com/v1/exports/audiences

Response

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.
name Required The name of the audience being exported
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.
results_count Required Number of rows in the export
results_generated_at Required The date that the result set expires.
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,
    "name": "Localytics",
    "source_type": "audiences",
    "source_id": "45644",
    "job_type": "idfa",
    "last_requested_at": "2017-02-13T14:30:47Z",
    "results_count": 6705543,
    "results_generated_at": "2017-02-13T12:30:43Z",
    "results_expire_at": "2017-06-02T11:06:39Z"
  },
  {
    "id": 7,
    "name": "Localytics2",
    "source_type": "audiences",
    "source_id": "4478",
    "job_type": "email",
    "results_count": 5105543,
    "results_generated_at": "2017-02-13T12:30:48Z",
    "results_expire_at": "2017-06-02T11:06:39Z"
  }
  ...
]

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.
1.5 05/30/2017 Added audience name and size to the audience list response

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.

Introduction

The Localytics Engagement Platform enables marketers to collect information about their user’s preferences, behaviors and interactions to be used in targeting and segmentation. A set of these data points for an individual user is a Profile. Profiles are used throughout our platform, and are increasingly becoming an integration point for our marketing cloud, customer relationship management system and other ecosystem partners. Localytics Profile Exports is a RESTful web service that enables our customers and partners to more rapidly build these user level integrations without a significant engineering investment.

Getting Started

Profile 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.
  • Profile ID - Uniquely identifies the set of Profiles being requested.

Configuring Profiles for Export

Before making a request to the API you must enable the set of Profiles you want to export via the Localytics Dashboard. To enable a given set of Profiles for the first time:

  1. Navigate to the Profiles Screen of the Application or Organization
  2. Click the Action menu and click Enable Profile Exports
  3. From the pop-up modal select the Application or Organization, Export Type and click Enable

Managing Profile 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:

  • Profile Exports are refreshed daily starting at 8 a.m. EST and typically finish within an hour.
  • A maximum of 5 Profile Exports, per organization, can be available to the API at a time with an Enterprise Analytics or Enterprise Marketing subscription.
  • You must first enable a particular Profile Export before attempting to request it via the API.
  • Profile Exports not requested in a 45 day period will stop being refreshed and be made unavailable via the API.

Profile Exports Transactions

Endpoint

The base URL for all requests is:

https://api.localytics.com/v1/exports/profiles/:profiledb_id/:job_type

Authentication

Profile 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

Profile Exports enforces the following rate limits per API Key:

  • 50 requests per minute.

Profile Exports 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

Export Parameters

Parameter Required? Description
profiledb_id Required This is a Localytics-generated identifier for the set of Profiles being exported. The profiledb_id will be formatted as a positive integer, and can be found here for apps and here for your org, both in the Settings screen of your Localytics Dashboard.

This can be found beside the app name in the Settings Screen

Example: 6012
job_type Required This is type of Profile Export that will be return. You can request a full export of all Profiles within a given ProfileDB ID or changes since the last time you requested an export for a given ProfileDB ID.

The job_type value must be one of the following:
Job Job_type
Export of entire Profile set profile
Export of changes since last request profile_changes

Example

Here is an example with profile_changes as the job type.

curl -L https://[api_key]:[api_secret]@api.localytics.com/v1/exports/profiles/6012/profile_changes

Response

Profile 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:

  {"_ll.language":"en", "favorite_place":"Mohit’s Crib"}
  {"_ll.language":"en", "favorite_place":"Paris"}
  {"_ll.language":"en", "favorite_place":"Rejuvenation Room"}}
  {"_ll.language":"en", "favorite_place":"Boston"}
  …
  {"deletes":{"attributes":["some_attrib1", "some_attrib2"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"_ll.country":"Spain", "favorite_place":"Boston"}}
  {"profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"_ll.country":"USA"}}
  {"deletes":{"attributes":["some_attrib1"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}}
  {"deletes":{"attributes":["some_attrib2"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"favorite_place":"Boston"}} 
  ...
  

Requesting a List of Available Exports

Endpoint

The base URL is:

https://api.localytics.com/v1/exports/profiles

Response

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.
name Required The name of the export
source_type Required The object being exported (ex. profile).
source_id Required The identifier of the object being exported.
job_type Required The type of data being exported (ex. profile_changes).
results_generated_at Optional The last time the results for this export were generated. If missing no results have been generated yet.
results_count Required The number of rows being exported.
results_expire_at Required The date that the result set expires.
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": 191,
    "name": "Localyticss_ios_app",
    "source_type": "profile",
    "source_id": "13724",
    "job_type": "profile_changes",
    "last_requested_at": "2017-02-13T14:30:47Z",
    "results_generated_at": "2017-02-13T12:30:43Z",
    "results_count": 43543,
    "results_expire_at": "2017-06-02T11:06:39Z"
  },
  {
    "id": 374,
    "name": "Localytics_android_app",
    "source_type": "profile",
    "source_id": "209478",
    "job_type": "profile",
    "results_generated_at": "2017-02-13T12:30:48Z",
    "results_count": 7843,
    "results_expire_at": "2017-06-02T11:06:39Z"
  }
  ...
]

HTTP Response Codes

Profile Exports return the following HTTP response codes:

Code Description
302 The Export 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 Exports.
404 The source type is unknown. Remember, it should always be “profiles” when using Profile Exports.
429 You’ve met your 10 request per minute limitation and are now being throttled.

Version History

Version Date Change Summary
0.5 05/04/2017 Beta release version.
1.0 08/25/2017 GA release version. Includes self-serve dashboard.


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!


Import

Profile Imports

Profile Imports allows you to import, in bulk, preferences and behaviors of new or existing users associated with your app for mobile engagement and analysis.

Introduction

The Localytics Engagement Platform enables marketers to collect information about their user’s preferences, behaviors and interactions to be used in targeting and segmentation. A set of these data points for an individual user is a Profile. Profiles are used throughout our platform, and are increasingly becoming an integration point for our marketing cloud, customer relationship management system and other ecosystem partners. Localytics Profile Imports is a RESTful web service that enables our customers and partners to update or add Profile and Attributes from other systems to more rapidly build these user level integrations.

Getting Started

Profile Imports 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.
  • Localytics ID - Either your Localytics app_id or org_id depending on the scope of your Profile upload.

Implementation Details

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

  • Profile Imports can be used to update existing Profile Attributes or add completely new Profiles and/or Attributes.
  • Profile Import jobs usually take less than 5 minutes to complete, once “Running”.

Profile Imports Transactions

Endpoint

The base URL for all requests is:

https://api.localytics.com/v1/imports/profiles/upload

Authentication

Profile Imports 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

Profile Imports enforces the following rate limit per API Key:

  • 10 requests per hour.

Profile Imports 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

Import Parameters

Parameter Required? Description
scope Required This defines the scope of the import. Each import must either be for an organization or specific application, but not both. Read more about Profile scopes here.

The scope must be one of the following:

Description Import_type
Organization ID for your organization scoped Profiles Import org_id
Application ID for your application scoped Profiles Import app_id

Example: org_id:60
format Required This is the format of the file being imported.

The format must be one of the following:
Description Format
JavaScript Object Notation (json) json
Comma Separated Values (csv.) csv.
file Required This is the location of the file being imported.
Example: @test_file.txt

Example

Here is an example with JSON as the format.

      curl \
      -F org_id=60 \
      -F format=json \
      -F file=@test_file.txt \
       https://[api_key]:[api_secret]@api.localytics.com/v1/imports/profiles/upload
     

Response

Profile Imports will return a 202 response code with an activity id that can be used to poll the status of the import job (explained below).

Example Response

  {"activity_id": "3b4a65e5-2beb-4011-85df-c9f594217d90"}
  

Requesting the Status of Import Jobs

Endpoint

The base URL is:

https://api.localytics.com/v1/imports/profiles/status/:activity_id

Rate Limits

The import status endpoint enforces the following rate limit per API Key:

  • 60 requests per minute.

Example

      curl https://[api_key]:[api_secret]@api.localytics.com/v1/imports/profiles/status/3b4a65e5-2beb-4011-85df-c9f594217d90
     

An import job status request will result in a JSON formatted response with the following information:

Field Required? Comment
status Required Either “Pending”, “Running”, “Failed”, or “Completed”
error_log Required URL to logs of failed rows in the job
target Required Profile scope of the job and associated IDs
upload_statistics Required Detailed counts associated with the import job

Sample Response

While the import is processing, you can expect one of the following responses:

{"status": "Pending" ... }
  {"status": "Running" ... }

After the import is processed, you can expect the following response:

  {
  "status": "Completed",
  "error_log": "profile-bulk-update-sandbox.s3.aws.com/errors/3b4a65e5-2beb-4011-85df-c9f594217d90/errors.json",
  "scopet": {"org_id": 1234},
  "upload_statistics": {
    "successful_imports": 99,
    "parsed_imports": 99,
    "failed_imports": 1,
    "total_number_of_imports": 100,
  }
}

HTTP Response Codes

Profile Imports return the following HTTP response codes:

Code Description
202 The request was successful and Localytics will queue your file for processing.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not have access to the specified organization or application.
404 The source type is unknown. Remember, it should always be “profiles” when using Profile Exports.
429 You’ve met your 10 request per hour (import endpoint) limitation or 60 request per minute (import status endpoint) and are now being throttled.

Version History

Version Date Change Summary
0.5 05/30/2017 Beta release version.


Audience Imports

Audience Imports allows you to import, in bulk, lists of users created in other platforms for engagement within Localytics.

Introduction

The Localytics Engagement Platform enables marketers to collect data about their users and use it for targeting and segmentation to drive more effective engagement. However, in some cases, marketers want to use data from internal systems or customer relationship management (CRM) solutions to create audiences outside of the Localytics Platform. Localytics Audience Imports is a RESTful web service that enables our customers to create audiences (or lists of users) on their own and import them into the Localytics Platform to be used in marketing campaigns just like an audience created via the Localytics Dashboard.

Getting Started

Audience Imports accepts HTTP POST 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 allow Localytics to properly identify the audience and process the import.

Implementation Details

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

  • Audience Imports can only be used to create a new audience list or to completely replace an existing audience list.
  • Audience Imports can be used to drive campaigns on any of the Localytics channels, however, they cannot be altered or combined with additional segmentation criteria in the Localytics Dashboard.
  • Successfully imported audience list will appear in the table on the Audience page within the Localytics Dashboard, with the “List” label under Type.

Audience Imports Transactions

Endpoint

The URL for all requests is:

https://api.localytics.com/v1/imports/audiences/list/

Authentication

Audience Imports 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 Imports enforces the following rate limit per API Key:

  • 60 requests per minute.

Audience Imports 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

Import Parameters

Parameter Required? Description
app_id Required This is the application-specific identifier associated with the imported audience.
audience_name Required This is the name of your new audience.
identifier_type Required At this time, “customer_id” is the only accepted identifier.
file Required A file consisting of JSON lines of customer IDs as specified below.

Example

Here is an example with customer_id as the identifier.

      curl \
      -F app_id=7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee \
      -F audience_name=my-audience-name \
      -F identifier_type=customer_id \
      -F file=@test_file.txt \
       https://[api_key]:[api_secret]@api.localytics.com/v1/imports/audiences/list/
     

Response

Audience Imports will return a 202 response code with an activity id that can be used to poll the status of the import job (explained below).

Example Response

  {"activity_id": "3b4a65e5-2beb-4011-85df-c9f594217d90"}
  

Import File Format

Whether you are creating a new audience or updating an existing one, the file format is the same. The attached file should be formatted according to the standard JSON lines text file format, where the lines of the file are all valid JSON. Each line should be a dictionary with one key, “customer_id”, and a valid customer ID as the value.

{“customer_id”:“abc”}
{“customer_id”:“123”}
{“customer_id”:“abc123”}

Requesting the Status of Import Jobs

Endpoint

The URL is:

https://[api_key]:[api_secret]@api.localytics.com/v1/imports/audiences/list/status/[activity_id]

Rate Limits

The import status endpoint enforces the following rate limit per API Key:

  • 60 requests per minute.

Example

      $ curl https://[api_key]:[api_secret]@api.localytics.com/v1/imports/audiences/list/status/123456
     

Example with incomplete status

 
  {"status":"Pending","error_reason”:null,“upload_statistics”: null, app_uuid":"abcde-12345-example-app-id","created_at":"2017-04-25T08:00:00","updated_at":"2017-04-25T08:00:00"}

Example with complete status
 
{"status":"Completed","app_uuid":"abcde-12345-example-app-id","upload_statistics":{"total_lines":"1","audience_id":"999","audience_list_id":"3","failed_lines":"3","successful_lines":"500"}}

Updating an Audience Import

Endpoint

The URL is:

https://api.localytics.com/v1/imports/audiences/list/[audience_list_id]

Request Parameters

Parameter Required? Description
app_id Required This is the application specific-identifier associated with the imported audience.
identifier_type Required At this time, “customer_id” is the only accepted identifier.
target Required Profile scope of the job and associated IDs
file Required A file consisting of JSON lines of customer IDs as specified below.
audience_list_id Required This is the id associated with the audience import. This can be found in the polling status response.

HTTP Response Codes

Audience Imports returns the following HTTP response codes:

Code Description
200 The request was successful and Localytics will queue your file for processing.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not have access to the specified organization or application.
404 Parameter not found.
429 You’ve met your rate limit and are now being throttled.

Version History

Version Date Change Summary
0.5 09/01/2017 Beta release version.