API Introduction

Leanplum is designed to integrate with your app using one of our mobile SDKs. However, If you need to send data to Leanplum from your backend systems, you can use our REST API. The Leanplum REST API is available to all our customers on full-service accounts. For best results, we recommend contacting your customer success manager to discuss your API integration needs, so we can review your plan and share best practices on how to integrate.

In the meantime, below you can review our common use cases for using our REST API.

Tracking Session and other User data

Leanplum organizes its data within sessions. A session is one use of an application by a user. To start a session, use the start API method. Sessions may be paused and resumed as users exit and re-enter the app, using pauseSession and resumeSession.

Sessions also include user activity, such as events (things the user does), and states (parts of the app the user is in). Send events and states using track and advance. User attributes may change within a session using setUserAttributes. Sessions time out after 2 hours of inactivity, or 30 minutes after being paused. To keep a session alive, use heartbeat.

Some things can happen outside of sessions as well. For example, a user may receive a notification or a friend request while they're not using the app. You can use track (with disposition=passive) and setUserAttributes outside of sessions.

Updating User Data

Leanplum stores many things in a user's profile, including user attributes and behavioral data, such as the lifetime occurrences of a particular event. You can update both of these with setUserAttributes. To retrieve a user's profile, use exportUser.

Sending messages

Leanplum allows you to create messages that are triggered based on user activity, such as when an event fires or a user attribute changes. But in some cases, you may need to trigger messages based on information available on your own server. Use the sendMessage API to send a push notification, newsfeed message, or other types of messages to a user.

The Leanplum SDK will automatically collect push tokens from your users, but if you need to import older push tokens (from users before Leanplum), you can set them in setDeviceAttributes.

Accessing Variable Data

There are APIs for receiving the user's variables and files set in the Leanplum dashboard in the Variables and A/B Testing tabs. Whenever a request executes the start method, the list of variables is returned. You can also get the user's variables without starting a new session using getVars. To access the file referenced by the value of a file variable, use downloadFile.


Use setTrafficSourceInfo to send attribution data for a user. You can also use setUserAttributes.

Data export

You can export raw user activity data using exportData, export lists of users that match certain criteria using exportUsers, or export analytics reports using exportReport. You can also add postbacks to stream data to another location when those events occur using addPostback.

Fetching created engagement content in Leanplum

You may need to retrieve information about A/B tests or messages created in the Leanplum dashboard. To retrieve information about A/B tests, use getAbTests, getAbTest , or getVariant. To retrieve information about messages, use getMessage or getMessages.

Check out the sample uses of our API Github samples.