Import APIs

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.