Events API

The Events API allows you to track server-side events that relate to an end user's in-app activity.


Localytics maintains platform-specific SDKs to help you measure and improve app engagement with ease, reliability, and precision. Our SDKs enable rich multi-channel messaging and make it simple for you to track user behavior by decreasing implementation complexity, providing bandwidth management/retry logic, and performing sophisticated de-duplication capabilities.

But in some situations, in-app activity alone does not provide a full picture of your customers' engagement. As the customer journey becomes more and more complex, marketers need to be able to execute in mobile channels regardless of where the customer touchpoint is.

For example: for eCommerce apps, the most important conversion events are typically purchases. An end user initiates a purchase in-app, but the purchase usually “finishes” on a merchant’s backend server infrastructure — after the merchant completes payment processing, inventory management, and shipping verification. The most reliable way to track purchases would be to use the Events API to record a “purchase complete” event when these processes are successfully completed.

Similar API-triggered events happen in other types of apps:

  • Smart-speaker skill invocation ("Alexa, ask the Sports_App when's the next game")
  • Purchase registered via a brick and mortar store Point of Sale
  • Account update performed via a request to a call center operator
The Localytics Events API allows you to track these types of events alongside event data captured from apps instrumented with the Localytics SDK.

Localytics processes web services calls to the Events API in near real-time (at equivalent speed to events tagged with a Localytics SDK). Events will be usable in Localytics Analytics and Marketing campaign performance reporting, and available for audience targeting.

Getting Started

The Events API accepts HTTP POST transactions authenticated with an API key/secret. At a high level, a transaction includes the following information:

  • Authentication - API key and secret that allows Localytics to authenticate your transaction.
  • One or more event requests.

Each event request within a transaction includes the following types of information:

  • App identification - Your app’s Localytics App ID.
  • User Data - Customer ID for an end user of your app.
  • Event Data - Data such as the event name, event time, event attributes (optional), and LTV change (optional).
  • Request Identifier - UUID that identifies each event request; used to ensure uniqueness/guarantee that each event request gets processed exactly once.

The Events API supports batching multiple event requests in JSON line format within the POST body of a single transaction. The POST body can be plaintext or compressed using gzip, but must be smaller than 256KB (usually about 250 events plaintext / 10,000 events compressed).

We recommend batching event requests within a single transaction to make it easier for your servers to accommodate changes in your request load.

Implementation Details

Events API requests must be associated with a valid App ID. Localytics provides a special type of app platform called API. This is specifically for integrations with clients—such as point of sale systems or smart speakers via API calls.

If you're using an API platform app, you'll be able to set the Customer ID via the Events API. If, however, you're using a non API app (for example, iOS or Android platform) the Customer ID must already be set within Localytics, and you'll want to use the Events API to reference that Customer ID (iOS/Android)

It is recommended that the App ID provided with the request is that of an API platform. Events API will accept requests with an App ID corresponding to a device app (for example, iOS or Android platform) however for such requests Localytics will apply events to the last device that a customer was active on. This means that unless you use API platform App ID, you can only send Events API requests for people who have used your app at least once.

When you instrument your app with a Localytics SDK, the Localytics platform helps you to understand your app engagement by allowing you to set Custom Dimensions and by tracking many important Dimensions automatically (e.g. Country, Language, App Version). Events API requests typically do not have access to most dimensions or sessions data. For the App IDs associated with device platforms the Events API makes it easy for you to track engagement along various Dimensions by tagging event requests with the last Dimensions recorded for the last device that a customer was active on. This means that if you employ the Events API to record a “purchase complete” event for a given end user, Localytics will assume that the user accomplished this event with his or her most recent values for Country, Language, Device, App Version, etc. This means that events recorded using the Events API can be used for targeting and to drive Analytics charts — akin to any in-app event.

At the API level, the Localytics Events API validates that your event request is correctly formatted, but does not perform extensive content-level validation. If you send a correctly-formatted event request with a non-API App ID for a person who has not used your app, the Events API will accept the request but will not create an event or a new user.

The same best practices that apply to events tagged using Localytics SDKs also apply to events created using the Events API. So you should deliberately structure your event names (not create hundreds or thousands of differently-named events), use consistent attributes for the same event, etc. Please be aware that events created using the Events API count towards your org’s monthly Datapoint allotment for billing purposes.

Events API Transactions

API Endpoint

The base URL for all transactions is:[api_version]/uploads
The most recent [api_version] is v1. This version may change in the future releases of Events API. The api version v0 that was used during the beta period is deprecated and its support will be removed in future versions.

The Content-Type HTTP header for each transaction should specify the format of the transaction's POST body (either application/json for plaintext or application/x-gzip for gzipped).


The Localytics Events API uses Basic Access Authentication. You can use your org’s API Key/Secret to authenticate Events API transactions. These are the same credentials you use to authenticate transactions with the Localytics Profile API or Push API.

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

Rate Limits

The Localytics Events API enforces the following rate limits per API Key:

  • 150 transactions per second.

Event Request Parameters

The Localytics Events API accepts event requests in JSON Line format according to a published schema. This means that each event request must be formatted as a single line. The individual event request within a transaction should be separated by a newline.

Parameter Required? Description
schema_url Required (String) URL indicating the Localytics Events API JSON Schema version for the event request.

For the most recent Events API version the schema URL must be:
app_uuid Required (String) Your Localytics App ID.

Example: 91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f
customer_id Required (String) Localytics Customer ID that identifies the end user who completed the event.

event_name Required (String) The name of the event; limited to 128 characters.

Example: Purchase_Completed
event_time Required (Integer) The time that the event occurred, in milliseconds since epoch (GMT). For example, a value of 1412090428444 would indicate an event time of "30 Sep 2014 15:20:28.444 GMT"

Event timestamps must be more recent than 72 hours in the past and must not exceed 2 days in the future.

Example: 1412090428444
uuid Required (UUID) UUID that uniquely identifies this event request; required to mitigate networking problems and ensure that each event is processed exactly once. The UUID should be randomly generated.

UUIDs must be 32-75 characters in length and contain only hex characters and dashes (0-9, a-f, A-F, -).

Example: fabfec96-7aff-40cc-a37d-972c4b4265de
attributes Optional (Object) JSON object containing key/value pairs representing user-defined event attribute names and their values.

An event can have up to 50 event attributes. Although Localytics supports numeric or string event attributes, attribute values of both types should be formatted as strings. Attribute names and values can be up to 128 characters in length.

Example: { "My String Attribute": "Value", "My Numeric Attribute": "235" }
ltv_change Optional (Integer) Incremental change in user’s lifetime value associated with this event. Must be an integer value ($2.99 = 299).

Example: 299


Transaction with a Single Event Request

    curl \
    -i -H "Accept application/json" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{ "schema_url": "", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "", "event_name": "Purchase_Completed", "event_time": 1412090428444, "uuid": "fabfec96-7aff-40cc-a37d-972c4b4265de", "attributes": { "My String Attribute": "Value", "My Numeric Attribute": "235" }, "ltv_change": 299 }' \

Transaction with Multiple Event Requests

    curl \
    -i -H "Accept application/json" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{ "schema_url": "", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "", "event_name": "Purchase_Completed", "event_time": 1412090428444, "uuid": "fabfec96-7aff-40cc-a37d-972c4b4265de", "attributes": { "My String Attribute": "Value", "My Numeric Attribute": "235" }, "ltv_change": 299 }
    { "schema_url": "", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "", "event_name": "Some_Event", "event_time": 1412090428488, "uuid": "8dbbbbe7-fe80-4ad9-ba5d-67679a0f20e5" }' \


The Localytics Events API will return a 202 response code if your transaction is correctly formatted. The Events API does not validate the correctness of the event requests within a transaction — a 202 response code only indicates that the transaction was accepted.

More precisely, the Events API will verify that:

  • Authorization succeeded
  • Request headers were properly-formatted
  • Content-Type was valid
  • If the POST body was gzipped, the gzip is valid
  • The POST body was ≤ 256 KB
  • The transaction was successfully accepted for processing
Individual event requests within a transaction may still fail during downstream processing if event request parameters are invalid, etc. The “Troubleshooting” section outlines best practices for verifying that your event requests are properly constructed.

HTTP Response Codes

The Localytics Events API returns the following HTTP response codes:

Code Description
202 The transaction was correctly formatted.
400 A required parameter is missing or malformed.
401 The supplied API key/secret parameters were not valid.
413 The POST body was larger than 256 KB.
  • The Content-Type was not valid (only application/json or application/x-gzip are allowed).
  • The Content-Type was application/x-gzip but the POST body did not contain a valid gzipped payload.
429 The transaction exceeded the API’s rate limit.


Localytics maintains versioned JSON schemas for Events API requests. The most current schema is v1:

To enable quick testing without actually creating events in Localytics, you can validate that your event requests are valid JSON with a linter such as:

And you can validate that your event requests match a Localytics JSON Schema by using using a JSON schema validator such as:

Like events tagged using a Localytics SDK, events that you create using the Events API cannot be deleted or removed. We strongly suggest that you employ a dev app_uuid (NOT your production app_uuid) when you develop and test services that use the Events API.


If the Localytics Events API rejects your transactions:

  • Are you authenticating your requests with your org’s API Key/Secret?

If the Localytics Events API accepts your transactions, but your event requests do not appear in the Localytics Dashboard within 20 minutes:

  • Have you tested that your event requests are valid JSON and conform to the appropriate JSON Schema?
  • Are the event requests in a transaction formatted as JSON lines? Specifically, line breaks in the POST body of a transaction should only separate event requests — there should not be line breaks between the JSON key-values in a single event request.
  • Does your app set customer_id?
  • Are you specifying the customer_id parameter in your event requests in the same format as the Customer ID you set in your app? For example, does your app set Customer ID to a hashed value of your system’s internal identifier?
  • Are you using API platform as your App ID? If not did the customer_id in your requests have a session in your app?
  • Are you specifying event_time in milliseconds since epoch? By default, the time libraries for some programming languages specify time in seconds since epoch.
  • Are you providing a unique uuid parameter with each event request?

Version History

Version Date Change Summary
0.1 5/10/2016 Initial draft.
0.2 5/25/2016 Revision for beta participants.
0.3 7/5/2016 Finalized API endpoint.
0.4 7/12/2016 Added JSON schema URL.
0.5 7/26/2016 Clarified JSON lines, revised endpoint versioning. Beta release version.
1.0 3/31/2019 Events API v1 release, includes support for API platforms.