Leanplum's user guides and developer documentation.

Leanplum Documentation

Leanplum's user guides, SDK setup, API docs, and more resources are here to help you get the most out of A/B testing, Campaigns, Messaging, and Analytics.

Prepare a CSV file to import user data

When importing user data with a CSV upload, you must include certain fields as columns in your CSV file, depending on the type of data you want to import.

See how to format your CSV file based on the type of data you want to import:

❗️

Check the file encoding

Check the file's encoding to ensure it doesn't have a Byte Order Mark. To check the encoding, you can open the file in Sublime Text and click File > Save with Encoding > "UTF-8" (not "UTF-8 with BOM").

User Attributes

To upload new users or user-level attributes, your CSV must include the user ID in the first column, with any attributes you want to upload in the following columns. You can also include the lastActive time and created date (unix).

Field

Data type

Required?

Description

userId

String

YES

The user ID. It must be the first column of the CSV file.

userAttributes.

String

NO

The name of the user attribute.
Example: userAttributes.facebook_id
We highly recommend validating the data here, for example, if it's an email.

created

Unix timestamp

NO

Use this to set the date and time the user was created. The value has to be in Unix time.
This will allow you to target users based on "time of first run," etc.

lastActive

Unix timestamp

NO

Use this to set the date and time the user was last active. The value has to be in Unix time.
This will allow you to target users based on "last active," etc.

📘

Don't forget about email

If you want to email your users, make sure the users' email addresses are included as an attribute in the CSV file. Otherwise, Leanplum will not be able to email these users.

Example file format:

userId

created

lastActive

userAttributes.age

userAttributes.gender

userAttributes.friends

sample_user

1496275200

1580496000

24

female

"[Jimmy, Sara, Amy]"

The above sample file will create a user profile like this:

Click to enlarge

Device attributes

To upload device-level attributes, you must include the user ID if there is one. You must also include the device ID.

🚧

Use the right API action

When importing device attributes, you must set the defaultAction to setDeviceAttributes in the API call.

Field

Data type

Required?

Description

userId

String

YES

The user id. It must be the first column of the CSV file.

deviceId

String

YES

The device id. A single user may have multiple device ids.

iosPushToken

String

NO

Use this to set the iOS push token of the device. Push tokens are device specific, so in the CSV file, you must specify which deviceId this token belongs to. This is done by having the device ID and the push token on the same row.

systemName

String

No

The value should be either iOS or Android OS. This must match the push token type you are uploading.

gcmRegistrationId

String

NO

Use this to set the Android push token of the device. Push tokens are device specific, so in the CSV file you must specify which deviceId this token belongs to. This is done by having the deviceId and the push token on the same row.

Example file format:

userId

deviceId

systemName

iosPushToken

gcmRegistrationId

background

sample_user1

ABC-123

iOS

1234567

TRUE

sample_user2

ABC-456

Android OS

7654321

TRUE

Events

When formatting your CSV for event uploads, you can import information on the number of occurrences of an event, the value of an event, the time an event first occurred, and more.

🚧

Use the right API action

When importing historical events, you must set the defaultAction to setUserAttributes in the API call.

Field

Data type

Required?

Description

userId

String

YES

The user ID. It must be the first column of the CSV file.

events.eventName.count

Integer

NO

New lifetime count of for the current user.

Always set when doing historical uploads (meaning when users have no recorded occurrences of the event yet in Leanplum)

events.eventName.firstTime

Unix Timestamp

NO

Time that the event first occurred, in seconds since midnight UTC on January 1, 1970.

events.eventName.lastTime

Unix Timestamp

NO

Time that the event last occurred, in seconds since midnight UTC on January 1, 1970.

events.eventName.countIncrement

Integer

NO

Amount to increment the lifetime count of eventName.

events.eventName.value

number(float)

NO

New lifetime value of for the current user.

events.eventName.valueIncrement

number(float)

NO

Amount to increment the lifetime value of eventName.

Example file format:

userId

events.Purchase.firstTime

events.Purchase.lastTime

events.Purchase.count

events.Purchase.value

sample_user

1496275200

1580496000

3

20

This sample creates a profile like this:

Click to enlarge

Now you can segment users based on the number of occurrences of the event in the Users page. For example:

From the Users page, select Add Segment > Behavioral > Occurrences of event or state to set up this segment, then edit the values for you event and the number of occurrences.

Email unsubscribe / resubscribe

Use the information below to create a CSV that unsubscribes or subscribes a list of users for email.

Managing subscribing/unsubscribing for the Email channel:

Field

Data type

Required?

Description

userId

String

YES

The user ID. It must be the first column of the CSV file.

unsubscribeChannelsToAdd

String

NO

Set to "Email" to unsubscribe users from all marketing emails.

unsubscribeChannelsToRemove

String

NO

Set to "Email" to resubscribe users from all marketing emails.

Example file format:

userId

unsubscribeChannelsToAdd

unsubscribeChannelsToRemove

sample_user1

Email

sample_user2

Email

Managing subscribing/unsubscribing for Email Categories:

Field

Data type

Required?

Description

userId

String

YES

The user ID. It must be the first column of the CSV file.

unsubscribeCategoriesToAdd

String/List

NO

Set to the IDs of the categories you wish to unsubscribe users from.

unsubscribeCategoriesToRemove

String/List

NO

Set to the IDs of the categories you wish to subscribe users to.

Example file format:

userId

unsubscribeCategoriesToAdd

unsubscribeCategoriesToRemove

sample_user1

2

sample_user2

["5""6""7""8"]

sample_user3

["1""6""7""13"]

["2""3""4""5"]

Updated about a month ago


Prepare a CSV file to import user data


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.