Overview

Leanplum is designed to integrate with your app using our SDKs. If you need to supplement our SDKs with information available from your backend systems, you can also use our API for these use cases. The Leanplum API is available only to customers on Full-Service accounts. We recommend you contact your customer success manager to discuss your API integration needs, so we can review your plan and share our best practices.

Sample uses of the API are on Github.

Client keys

Every Leanplum app you create will have multiple API keys (visible in App Settings > Keys & Settings). Set the clientKey parameter in the API request equal to the correct key when using one of its associated API methods:

  • Production: track sessions, states, set user or device attributes, etc.
  • Development: import CSV data, delete users, set variables, etc.
  • Data Export: export user data, messaging and a/b test reports, etc.
  • Content Read-only: get message and a/b test information, etc.

For more information on general usage, see Common tasks.

Users and Devices

For many API methods, you can pass a userId, a deviceId, or both userId and deviceId. Here's how these will affect the action, or execution of the API method:

  • userId only: The API action pertains to the user and not a particular device. In most cases, Leanplum will not associate any device with this action, which may cause device information to be excluded from analytics. In some cases, Leanplum may be able to infer the device. When using the sendMessage method for a push notification, passing a userId only would send a push notification to all devices associated with that user.
  • deviceId only: The API action pertains to a particular device without an associated user ID, for example, a logged out user. The user ID may be inferred by the API.
  • userId and deviceId: The API action pertains to a particular device associated to a particular user ID.

In many cases, you would only pass a userId and not a deviceId, because events coming from the API are not associated with a particular device. Events coming from a device are usually sent via the SDK.

Additionally, getVars has an additional mode where neither a userId nor deviceId are provided, which will return the default variables that would be seen by a blank user.

Request formats

All API requests must be made to https://www.leanplum.com/api. The API is very flexible and supports GET and POST request formats. Our docs, generally, use POST examples for methods that might update/change Leanplum data (e.g. start or setUserAttributes), but both GET and POST request methods are acceptable.

GET

The top-level arguments are sent as GET parameters in the request. As part of the HTTP specification, a URL must be at most 2,083 characters, so it's best for small API requests. All characters in the URL should be URL encoded.

Example:

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&apiVersion=1.0.6&userId=USER_ID&action=setUserAttributes&userAttributes={"Interests":["Technology","Music"]}

Properly encoded this is:

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&apiVersion=1.0.6&userId=USER_ID&action=setUserAttributes&userAttributes=%7B%27Interests%27%3A+%5B%27Technology%27%2C+%27Music%27%5D%7D

POST

The top-level arguments can be either in the URL or in the request body. Our docs, generally, show the action argument set in the URL for POST requests. This is not necessary; all arguments can be set in the POST body with the request sent to https://www.leanplum.com/api. Alternatively, more (even all) arguments can be placed in the URL. However, all characters in the URL should be URL encoded.

The Content-Type of the POST request must be JSON or multipart form data.

Example of a POST request with JSON:

POST https://www.leanplum.com/api?action=setUserAttributes

Content-Type: application/json
{
  "appId": "APP_ID",
  "clientKey": "CLIENT_KEY",
  "apiVersion": "1.0.6",
  "userId": "USER_ID",
  "userAttributes": {
    "Interests": [
      "Technology",
      "Music"
    ]
  }
}

Multiple actions can be batched together. It's highly recommended to batch API actions, especially for the same user. Do not make multiple concurrent API requests for the same user. See multi to learn about batching.

Responses

All responses except for the downloadFile request are in JSON format. Generally, “success”: true means the request was a valid request and was received and processed correctly by the API.

A HTTP response of 200, and a response of success=true does not mean that an action was taken by our API.

Types of responses you can get:

  1. HTTP 200 with success=true: The request was received and the action taken successfully.
  2. HTTP 200 with success=true and warning.message=“warning message": The request was received successfully but the action was likely skipped. See warning message for details.
  3. HTTP 200 with success=true and error.message=“error message": The request was received successfully but the action was skipped. See error message for details.
  4. HTTP 4xx or 5xx with success=false and error.message=“error message": The request was not received successfully. See error message for details.

To verify the API action was taken, it is important to verify that the the warning and error objects do not contain a message (in addition to verifying the success boolean and HTTP status).

Debugging

To debug an API request, set clientKey=DEVELOPMENT_KEY, devMode=true, and most importantly set userId=A_TEST_USER and/or deviceId=A_TEST_DEVICE. These requests will be visible in the Dashboard Debugger console.

All session and tracking info from these requests will not be tracked as real user data. The matching user/device will be set to a developer account, and all of their activity will be sent to a separate analytics section, Developer Activity.

Do not set devMode=true for any API request that involves a real device or user. Only use it with test devices or developer accounts.

Billing

Due to our system architecture, our costs increase for every user profile we need to retrieve in order to process an HTTP request to our API. As such, we bill server-side API calls based on the number of user lookups per HTTP request to our API, and not the number of HTTP requests or API actions.

To be clear, for billing purposes, a server-side API call is one unique user lookup initiated by an HTTP request made to the Leanplum API from any source other than the Leanplum SDK.

One HTTP request can include multiple user lookups. multi allows you to batch multiple actions affecting up to 50 unique users in a single request. Therefore, the maximum number of billable API calls (user lookups) per HTTP request is 50, not 1.

We do, however, exempt all deleteUser actions from billing so you're free to clean up your data.

We also optimize how we handle multi requests to prevent duplicate user lookups (reducing both our and your costs). Because we do this, you can reduce the number of billable calls you make to the Leanplum API (while executing the same number of actions) by batching actions for the same user(s).

See Best Practices on reducing calls for more.

Note: The multi action also allows you to import an external file containing a potentially large number of actions. This is billed by breaking the file into API requests that each contain a batch of 50 actions. Each of these API requests is then billed using the above definition.