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 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.
• 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

Import Parameters

Example

Here is an example with JSON as the format.

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

Postman example:

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"}
  

Import File Format

Whether you are creating new profile attributes or updating existing ones, 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 two keys, "customer_id" and "changes".

  {"customer_id":"abc","changes":[{"op":"assign","attr":"example1","value":"value1"}]}
  {"customer_id":"123","changes":[{"op":"set-add","attr":"example2","value":["value1", "value2"]}]}
  {"customer_id":"zxc","changes":[{"op":"set-remove","attr":"example3","value":["value1", "value2"]}]}
  {"customer_id":"abc","changes":[{"op":"increment","attr":"foo","value":1}]}
  {"customer_id":"zxc","changes":[{"op":"delete","attr":"foo"}]}
  

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:

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:

Version History

Introduction

Localytics 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 Localytics 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 - Organization’s 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, completely replace an existing audience list, delete an audience list, or rename an 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.
• 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.
• 500 Audience Lists

Audience Imports Request Parameters

Authentication Parameters

Import Parameters

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”}
     

Example: Creating an audience

      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/
     

import requests

files = {
    'app_id': (None, '7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee'),
    'audience_name': (None, 'my-audience-name'),
    'identifier_type': (None, 'customer_id'),
    'file': ('test_file.txt', open('test_file.txt', 'rb')),
}
response = requests.post('https://[api_key]:[api_secret]@api.localytics.com/v1/imports/audiences/list/', files=files)
     

Postman example:

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"}
  

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/3b4a65e5-2beb-4011-85df-c9f594217d90
     

import requests
response = requests.get('https://[api_key]:[api_secret]@api.localytics.com/v1/imports/audiences/list/status/3b4a65e5-2beb-4011-85df-c9f594217d90')
     

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"}
        

{"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

HTTP Response Codes

Audience Imports returns the following HTTP response codes:

Version History