Selecting a user

For many API methods, you are required to pass a userId, a deviceId, or both userId and deviceId to complete the request. Depending on which will need to be included, here is how each will affect the action you want executed within our REST API method:

User ParameterDescription
userIdThe API action pertains to the user and not a particular device. In most cases, Leanplum will not associate an API action with any device, which will cause device information to be excluded from analytics. When using the sendMessage method for a push notification, only passing a userId is required to send a push notification to all devices associated with that user.
deviceIdThe API action pertains to only a particular device without an associated user ID. An example of this is a logged out user. In that case the user ID will be inferred by the API.
userId and deviceIdThe API action pertains to a particular userId on or associated with a particular device user ID.

In the majority of cases, you will need only to pass a userId and not a deviceId. This is because events coming from the API are generally not associated with any particular device. Events coming from a device are usually sent via the SDK.

// Example POST requests to 
// https://api.leanplum.com/api?action=sendMessage

curl --location -g --request POST 'https://www.leanplum.com/api?action=sendMessage' \
--header 'Content-Type: application/json' \
--data-raw '{ <see below for relevant example > }'


// User only - sends message to all devices for that user
{
  "appId": "APP_ID",
  "clientKey": "PROD_KEY",
  "apiVersion": "1.0.6",
  "userId": "USER_ID",
  "messageId": 101001
}

// Device only - sends to a specific device
{
  "appId": "APP_ID",
  "clientKey": "PROD_KEY",
  "apiVersion": "1.0.6",
  "deviceId": "DEVICE_ID",
  "messageId": 101001
}

// User and device - sends to a specific device and user
{
  "appId": "APP_ID",
  "clientKey": "PROD_KEY",
  "apiVersion": "1.0.6",
  "userId": "USER_ID",
  "deviceId": "DEVICE_ID",
  "messageId": 101001
}

NOTE: The getVars API method has a mode where when neither a userId nor deviceId are provided, we will return the default variable values in Leanplum