{ "openapi": "3.0.0", "x-api-id": "leanplum-api", "x-send-defaults": true, "x-explorer-enabled": false, "x-samples-enabled": false, "info": { "version": "1.0", "title": "API", "description": "An API to perform actions from a server or remote device." }, "security": [ { "appIdQuery": [] }, { "clientKeyQuery": [] } ], "paths": { "/api?action=advance": { "post": { "tags": [ "User Behavior" ], "summary": "advance", "description": "Advances a user to the next state. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below). The state is the section of the app the user is currently in. States are like events with duration.\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId", "state" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "state": { "description": "The name of the state. Set to an empty string to leave the current state but not enter a new one.", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateNever`.\n", "default": "CreateNever", "type": "string", "enum": [ "CreateIfNeeded", "CreateNever" ] }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "info": { "description": "Any info attached to the state.", "type": "string" }, "params": { "description": "A flat object of parameters as key-value pairs. Each key must be a string, and up to 50 parameters may be set. Example: `{'gender':'F','age':21}`.\n", "type": "string", "format": "object" } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=pauseState": { "post": { "tags": [ "User Behavior" ], "summary": "pauseState", "description": "Pauses the current state, but not the session, for a user. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=resumeState": { "post": { "tags": [ "User Behavior" ], "summary": "resumeState", "description": "Resumes the current state for a user. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=pauseSession": { "post": { "tags": [ "User Behavior" ], "summary": "pauseSession", "description": "Pauses the current session and state for a user. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=resumeSession": { "post": { "tags": [ "User Behavior" ], "summary": "resumeSession", "description": "Resumes the current session and state for a user. Use either after `pauseSession`, or `start` if the app started in the background. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=heartbeat": { "post": { "tags": [ "User Behavior" ], "summary": "heartbeat", "description": "Sends a pulse to indicate that the current session is still in progress, so as not to automatically end it. Sessions are automatically timed out after 2 hours of inactivity \u2014 or 30 minutes if the session was paused first. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=start": { "post": { "tags": [ "User Behavior" ], "summary": "start", "description": "Starts a new session and returns the variables that have changed for the user. If the user/device does not exist, a new user will be created (see the `createDisposition` option below). This method requires your production API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateIfNeeded`.\n", "default": "CreateIfNeeded", "enum": [ "CreateIfNeeded", "CreateNever" ], "type": "string" }, "appVersion": { "description": "The version of the app used on this device. E.g. `2.0.1`.\n", "type": "string" }, "systemName": { "description": "The name of the OS the current device is running. E.g. `iOS`.\n", "type": "string" }, "systemVersion": { "description": "The version number of the OS the current device is running. E.g. `6.0`.\n", "type": "string" }, "browserName": { "description": "The name of the browser the current device is running. E.g. `Chrome`.\n", "type": "string" }, "browserVersion": { "description": "The version number of the browser the current device is running. E.g. `17.0`.\n", "type": "string" }, "deviceName": { "description": "A human-readable name representing the device.", "type": "string" }, "deviceModel": { "description": "The model name of the device. E.g. `iPad`.\n", "type": "string" }, "iosPushToken": { "description": "The token used for Apple iOS push notifications on this device.", "type": "string" }, "gcmRegistrationId": { "description": "The registration ID used for Google Cloud Messaging push notifications on this device.", "type": "string" }, "webPushSubscription": { "description": "The JSON-encoded subscription used for web push notifications on this device.", "type": "string" }, "userAttributes": { "type": "string", "format": "object", "description": "A map of user attributes as key-value pairs. Each key must be a string. Attributes are saved across sessions. Only supplied attributes will be updated (i.e., if you omit an existing attribute, it will be preserved). Example: `{\"gender\":\"F\",\"age\":21}`.\n" }, "locale": { "description": "The current locale the user is in. E.g. `en_US`.\n", "type": "string" }, "country": { "description": "The country the user is in, specified by [ISO 2-letter code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). E.g. `US` for United States. Set to `(detect)` to detect the country based on the IP address of the user.\n", "type": "string" }, "region": { "description": "The region (state) the user is in. E.g. `ca` for California. Set to `(detect)` to detect the region based on the IP address of the user.\n", "type": "string" }, "city": { "description": "The city the user is in. E.g. `San Francisco`. Set to `(detect)` to detect the city based on the IP address of the user.\n", "type": "string" }, "location": { "description": "The location (latitude/longitude) of the user. E.g. `37.775,-122.4183`. Set to `(detect)` to detect the location based on the IP address of the user.\n", "type": "string" }, "locationAccuracyType": { "description": "The type of location that is provided (IP, CELL, or GPS). Default: `IP`.\n", "type": "string" }, "timezone": { "description": "The timezone abbreviation for the user. See [list of timezone abbreviations](http://en.wikipedia.org/wiki/List_of_time_zone_abbreviations).\n", "type": "string" }, "timezoneOffsetSeconds": { "description": "The timezone offset from GMT in seconds.", "type": "number", "format": "integer" }, "background": { "description": "Whether the app started in the background. In this case, the session won't be counted until `resumeSession` is executed. Default: `false`.\n", "type": "boolean" }, "includeDefaults": { "description": "Whether to include default (\"defaults in code\") values in output. Default: `true`.\n", "type": "boolean" } } } } }, "description": "JSON request body.", "required": true }, "responses": { "default": { "description": "A successful request will return a response array with an object that has a success value set to true, and no error or warning object. It will also include variables, messages and other details relevant to that user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "description": "Response object for the API action.", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].messages": { "type": "object", "description": "In-app messages targeted at this user." }, "response[].vars": { "type": "object", "description": "Key/value pairs for variables.", "properties": { "varName": { "type": "string", "description": "The value of the variable `varName`." } } }, "response[].interfaceRules": { "type": "array", "description": "Custom visual events and UI settings from UI Editor.", "items": { "type": "object" } }, "response[].variants": { "type": "array", "description": "List of variants that the user belongs to.", "items": {} }, "response[].variants[].id": { "type": "number", "description": "ID of the variant." }, "response[].regions": { "type": "object" }, "response[].interfaceEvents": { "type": "array", "description": "Interface events information.", "items": { "type": "object" } }, "response[].token": { "type": "string" } } } } } } }, "deprecated": false } }, "/api?action=stop": { "post": { "tags": [ "User Behavior" ], "summary": "stop", "description": "Ends the current session. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below). This method requires your production API `clientKey`.\n", "requestBody": { "$ref": "#/components/requestBodies/Body" }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=track": { "post": { "tags": [ "User Behavior" ], "summary": "track", "description": "Tracks one occurrence of an event for a user. If the user/device does not exist, a new user will be created (see the `createDisposition` option below). This method requires your production API `clientKey`. See [tracking events via API](https://docs.leanplum.com/reference/api-guides#tracking-analytics-data-via-api) for examples.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "userId", "event" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateIfNeeded`.\n", "default": "CreateIfNeeded", "enum": [ "CreateIfNeeded", "CreateNever" ], "type": "string" }, "event": { "description": "The name of the event. Use \"Purchase\" to identify a monetization event, with the event value being the revenue. You can change the default monetization event name in Analytics by going to the metric chooser and clicking the Monetization metric category.", "type": "string" }, "value": { "description": "The event value. For example, for a purchase event, this would be the purchase price.", "type": "number", "format": "float" }, "currencyCode": { "description": "The ISO 4217 currency code associated with `value`. Leanplum will automatically convert `value` into your preferred currency, while retaining the original price and currency code as event parameters `localCurrency` and `localPrice`. Currency conversion rates are updated every hour.\n", "type": "string" }, "info": { "description": "Any info attached to the event.", "type": "string" }, "time": { "type": "number", "description": "Option to provide the UNIX timestamp for when the event occurred, which may be different from the current time.", "format": "float" }, "params": { "description": "A flat object of parameters as key-value pairs. Each key must be a string, and up to 50 parameters may be set. Example: `{\"gender\":\"F\",\"age\":21}`.\n", "type": "string", "format": "object" }, "messageId": { "description": "The message ID this event is associated with. Set this to track a user's interaction with a message. To track a message Send or a View, set the event argument to an empty string. For other interactions, set the event argument to the type of action (example values include Open, Cancel, Accept). The Leanplum SDK does this automatically, so this should be used for advanced use cases only.", "type": "number", "format": "integer" }, "disposition": { "description": "Determines how tracked events affect sessions and user activity. If present, disposition must have one of the following values:\n * `active` (default): Used for events reflect user activity. Active events should mark the user as active, and should be tracked within a session. (Replaces the deprecated option `allowOffline: false`.)\n * `passive`: Used for events that do not correspond to user activity. These events do not need to occur within a session, and do not mark a user as active. For example, sending a user a message would be tracked passively, since it affects a user, but does not represent user activity. (Replaces the deprecated option `allowOffline: true`.)\n * `requireActive`: Used for events that must only be tracked within a session. These events are rejected, and return a warning response with `ignored: true` if the user does not have an active session. Clients should detect the warning by the `ignored` field, as warning messages may change.\n", "type": "string", "enum": [ "active", "passive", "requireActive" ] } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=setUserAttributes": { "post": { "tags": [ "User Information" ], "summary": "setUserAttributes", "description": "Sets user attributes for the user given by userId and/or deviceId. If the user has an open session, the attributes for the current session will also be updated. Attributes will then propagate on data going forward. User properties not supplied in this method will not be affected. If the user/device does not exist, a new user will be created (see the `createDisposition` option below).\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateIfNeeded`.\n", "default": "CreateIfNeeded", "enum": [ "CreateIfNeeded", "CreateNever" ], "type": "string" }, "userAttributes": { "type": "string", "format": "object", "description": "A map of user attributes as key-value pairs. Each key must be a string. Attributes are saved across sessions. Only supplied attributes will be updated (i.e., if you omit an existing attribute, it will be preserved). Example: `{\"gender\":\"F\",\"age\":21}`.\n" }, "userAttributeValuesToAdd": { "type": "string", "format": "object", "description": "A map of values to add to existing user attribute sets. For example, supply `{\"Interests\":\"Sports\"}` to add Sports to the existing set of Interests.\n" }, "userAttributeValuesToRemove": { "type": "string", "format": "object", "description": "A map of values to remove from existing user attribute sets. For example, supply `{\"Interests\":\"Sports\"}` to remove Sports from the existing set of interests.\n" }, "userAttributeValuesToIncrement": { "type": "string", "format": "object", "description": "A map of values to increment onto existing user attributes. The existing attribute value and the increment must both be integers or the operation will be skipped. If the existing attribute is not set, its value will be inferred as 0.\n\nFor example, supply `{\"unreadMessages\":1}` to add 1 to the number of unread messages.\n" }, "unsubscribeCategoriesToAdd": { "type": "array", "description": "A list of email categories to unsubscribe a user from. See [Managing emails subscriptions via API](https://docs.leanplum.com/docs/manage-email-subscriptions#section-manage-subscriptions-with-the-leanplum-api) for more info.", "items": { "type": "string", "description": "The email subscription category ID." } }, "unsubscribeCategoriesToRemove": { "type": "array", "description": "A list of email categories to re-subscribe a user to.", "items": { "type": "string", "description": "The email subscription category ID." } }, "unsubscribeChannelsToAdd": { "type": "string", "description": "A messaging channel (e.g. `Email`, `Push Notification`, `Webhook`, `Newsfeed Message` App inbox) to unsubscribe the user from. Use this to unsubscribe a user from all marketing email categories.\n" }, "unsubscribeChannelsToRemove": { "type": "string", "description": "A messaging channel (e.g. `Email`, `Push Notification`, `Webhook`, `Newsfeed Message` App inbox) to re-subscribe the user to. Use this to re-subscribe a user to all marketing email categories (except any categories they have unsubscribed from).\n" }, "newUserId": { "type": "string", "description": "If supplied, updates the user of the current session with newUserId. This can have certain effects:\n* **Login**: If the current user has no user ID and the user given by newUserId already exists, the current and existing user profiles will be merged, and the current profile will be deleted.\n* **Register**: If there is no current user ID and the user given by newUserId does not exist, the current user will be simply assigned newUserId as its user ID.\n* **Switch user**: If the current user has a user ID, the current session will be ended and a new session will be started with the user given by newUserId. A user with newUserId will be created if one does not already exist.\n" }, "events": { "type": "string", "format": "object", "description": "A map of event data to update for the current user. The keys are the event names, each should have a nested object with at least one of the following attributes:\n\n * **count**: New lifetime count of this event for the current user.\n * **countIncrement**: Amount to increment the lifetime count of this event.\n * **value**: New lifetime value of this event for the current user.\n * **valueIncrement**: Amount to increment the lifetime value of this event.\n * **firstTime**: Time that this event first occurred, in seconds since midnight UTC on January 1, 1970.\n * **lastTime**: Time that this event last occurred, in seconds since midnight UTC on January 1, 1970.\n\nExample: Here's how to set the lifetime count for an event called \"myEvent\":\n\n`{ \"myEvent\": { count: 1 } }`\n" }, "states": { "type": "string", "format": "object", "description": "A map of state data to update for the current user. The keys are the state names, and each should have a nested object with at least one of the following attributes:\n\n * **count**: New lifetime count of this state for the current user.\n * **countIncrement**: Amount to increment the lifetime count of this state.\n * **firstTime**: Time that this state first occurred, in seconds since midnight UTC on January 1, 1970.\n * **lastTime**: Time that this state last occurred, in seconds since midnight UTC on January 1, 1970.\n\nExample: Here's how to set the lifetime count for a state called \"splashPage\":\n\n`{ \"splashPage\": { count: 23 } }`\n" }, "created": { "type": "number", "format": "float", "description": "The time at which the user was created, in seconds since midnight UTC on January 1, 1970." }, "lastActive": { "type": "number", "format": "float", "description": "The time at which the user was last active, in seconds since midnight UTC on January 1, 1970." }, "totalSessions": { "type": "number", "format": "integer", "description": "The total number of sessions that a user has had in their lifetime." }, "timeSpentInApp": { "description": "The total number of seconds spent in the app in the user's lifetime.", "type": "number", "format": "float" }, "locale": { "description": "The current locale the user is in. E.g. `en_US`.\n", "type": "string" }, "country": { "description": "The country the user is in, specified by [ISO 2-letter code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). E.g. `US` for United States. Set to `(detect)` to detect the country based on the IP address of the user.\n", "type": "string" }, "region": { "description": "The region (state) the user is in. E.g. `ca` for California. Set to `(detect)` to detect the region based on the IP address of the user.\n", "type": "string" }, "city": { "description": "The city the user is in. E.g. `San Francisco`. Set to `(detect)` to detect the city based on the IP address of the user.\n", "type": "string" }, "location": { "description": "The location (latitude/longitude) of the user. E.g. `37.775,-122.4183`. Set to `(detect)` to detect the location based on the IP address of the user.\n", "type": "string" }, "locationAccuracyType": { "description": "The type of location that is provided (IP, CELL, or GPS). Default: `IP`.\n", "type": "string" }, "timezone": { "description": "The timezone abbreviation for the user. See [list of timezone abbreviations](http://en.wikipedia.org/wiki/List_of_time_zone_abbreviations).\n", "type": "string" }, "timezoneOffsetSeconds": { "description": "The timezone offset from GMT in seconds.", "type": "number", "format": "integer" }, "devices": { "type": "array", "description": "A list of device objects associated with this user.", "items": { "type": "object", "properties": { "deviceId": { "description": "The unique ID for the device.", "type": "string" }, "appVersion": { "description": "The version of the app used on this device. E.g. `2.0.1`.\n", "type": "string" }, "systemName": { "description": "The name of the OS the current device is running. E.g. `iOS`.\n", "type": "string" }, "systemVersion": { "description": "The version number of the OS the current device is running. E.g. `6.0`.\n", "type": "string" }, "browserName": { "description": "The name of the browser the current device is running. E.g. `Chrome`.\n", "type": "string" }, "browserVersion": { "description": "The version number of the browser the current device is running. E.g. `17.0`.\n", "type": "string" }, "deviceName": { "description": "A human-readable name representing the device.", "type": "string" }, "deviceModel": { "description": "The model name of the device. E.g. `iPad`.\n", "type": "string" }, "iosPushToken": { "description": "The token used for Apple iOS push notifications on this device.", "type": "string" }, "gcmRegistrationId": { "description": "The registration ID used for Google Cloud Messaging push notifications on this device.", "type": "string" }, "webPushSubscription": { "description": "The JSON-encoded subscription used for web push notifications on this device.", "type": "string" } } } }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=setDeviceAttributes": { "post": { "tags": [ "User Information" ], "summary": "setDeviceAttributes", "description": "Sets device-level attributes, such as a deviceId or an iOS push token, for the current device. If the device is shared between multiple users, pass a `userId` with the `deviceId` to update the device for each user. (Passing just the `deviceId` will only update it once). If the device already exists, the attributes will be updated. If the device and user do not exist, a new user will be created along with this device (see the `createDisposition` option below). See [selecting a user](#selecting-a-user) for more.\n\nSee [Importing iOS push tokens](https://docs.leanplum.com/docs/importing-historical-push-tokens) for an example using setDeviceAttributes. This method requires your production API `clientKey`.\n\n> At least one of the following must be set to create/update a device: `appVersion`, `systemName`, `systemVersion`, `browserName`, `browserVersion`, `deviceName`, `deviceModel`, `iosPushToken`, `gcmRegistrationId`, or `webPushSubscription`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "deviceId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "deviceId": { "description": "The unique ID for the device.", "type": "string" }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateIfNeeded`.\n", "default": "CreateIfNeeded", "enum": [ "CreateIfNeeded", "CreateNever" ], "type": "string" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "appVersion": { "description": "The version of the app used on this device. E.g. `2.0.1`.\n", "type": "string" }, "systemName": { "description": "The name of the OS the current device is running. E.g. `iOS`.\n", "type": "string" }, "systemVersion": { "description": "The version number of the OS the current device is running. E.g. `6.0`.\n", "type": "string" }, "browserName": { "description": "The name of the browser the current device is running. E.g. `Chrome`.\n", "type": "string" }, "browserVersion": { "description": "The version number of the browser the current device is running. E.g. `17.0`.\n", "type": "string" }, "deviceName": { "description": "A human-readable name representing the device.", "type": "string" }, "deviceModel": { "description": "The model name of the device. E.g. `iPad`.\n", "type": "string" }, "iosPushToken": { "description": "The token used for Apple iOS push notifications on this device.", "type": "string" }, "gcmRegistrationId": { "description": "The registration ID used for Google Cloud Messaging push notifications on this device.", "type": "string" }, "webPushSubscription": { "description": "The JSON-encoded subscription used for web push notifications on this device.", "type": "string" } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=setTrafficSourceInfo": { "post": { "tags": [ "User Information" ], "summary": "setTrafficSourceInfo", "description": "Sets traffic source information for the current session of a user. If the user/device does not exist, a new user will be created (see the `createDisposition` option below). This method requires your production API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "userId", "trafficSource" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateIfNeeded`.\n", "default": "CreateIfNeeded", "enum": [ "CreateIfNeeded", "CreateNever" ], "type": "string" }, "trafficSource": { "type": "object", "description": "An object of traffic source parameters.", "required": [ "publisherId", "publisherName", "publisherSubPublisher", "publisherSubSite", "publisherSubCampaign", "publisherSubAdGroup", "publisherSubAd" ], "properties": { "publisherId": { "type": "string", "description": "ID of the publisher used to refer the user. Example: `1001`.\n" }, "publisherName": { "type": "string", "description": "Name of the publisher used to refer the user. Example: `Big Fish Games`.\n" }, "publisherSubPublisher": { "type": "string", "description": "Name of the developer used to refer the user. Example: `GameDeveloper1`.\n" }, "publisherSubSite": { "type": "string", "description": "Name of the app or website used to refer the user. Example: `MyLittleApp`.\n" }, "publisherSubCampaign": { "type": "string", "description": "Name of the campaign used to refer the user. Example: `US CPI`.\n" }, "publisherSubAdGroup": { "type": "string", "description": "Name of the ad group used to refer the user. Example: `banners`.\n" }, "publisherSubAd": { "type": "string", "description": "Name of the ad used to refer the user. Example: `blue1`.\n" } } }, "time": { "description": "The time at which the session started, in seconds since midnight UTC on January 1, 1970. This should be no more than 2 minutes after the session started. If not provided, uses the current time.", "type": "number", "format": "float" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false } } } } }, "description": "JSON request body with traffic source information.", "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=registerDevice": { "post": { "tags": [ "User Information" ], "summary": "registerDevice", "description": "Registers the current device for development. This method requires your development API `clientKey`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "deviceId", "email" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "deviceId": { "type": "string", "description": "A unique ID for the device to be registered by the request." }, "email": { "description": "The email address corresponding to the Leanplum user account to which the device belongs.", "type": "string" } } } } }, "required": true }, "responses": { "default": { "description": "Returns the status of the request and device registration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].registered": { "type": "boolean", "description": "Whether the device was just registered. If the device has already been registered, this will be `false`.\n" } } } } } } }, "deprecated": false } }, "/api?action=deleteUser": { "post": { "tags": [ "User Information" ], "summary": "deleteUser", "description": "Permanently removes all of a user\u2019s attribute information from our database. To erase a user\u2019s data entirely \u2014 including attribute, analytics, and sessions data \u2014 set the `fullErasure` flag to true. You can bulk delete users with [multi](reference#post_api-action-multi) (import mode) or contact our support team for assistance. `deleteUser` calls are exempt from API billing.\n\nThis method requires your development API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The user ID to delete. Required unless using `deviceId`.", "type": "string" }, "deviceId": { "description": "Required if no `userId`. The deviceId to delete. Only use this if there is no userId set. Note that `deviceId` will only delete data from devices where a user has never logged-in. If a logged-in user has been on the device, you must call the `deleteUser` API with the `userId`.", "type": "string" }, "fullErasure": { "description": "Deletes all session and analytics data for the selected user. This may take up to 15 days to process fully. Defaults to false \u2014 should be set to `true` for GDPR-related deletion requests.", "type": "boolean" } } } } }, "description": "JSON request body with variables and values.", "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=block": { "post": { "tags": [ "User Information" ], "summary": "block", "description": "Stops all data collection for a user going forward. `block` also erases any data previously associated with that user, including all of their attribute and analytics data. The block will take effect as soon as the \u201csuccess\u201d response is returned. It may take up to 15 days to delete the user\u2019s data completely.\n\nNote that the `block` call deletes a user's past data, but does not delete the user entirely. This allows you to use the `unblock` call to resume data collection.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "type": "string", "description": "The `userId` to block data collection for. **Required unless you use** `deviceId`. See below for details." }, "deviceId": { "type": "string", "description": "The `deviceId` to block data collection for. **Required if no** `userId`.\nA deviceId `block` will only block data from devices where a user has not logged-in on the device. If a user has logged-in on the device before, you must call the `block` API with the `userId`." }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=unblock": { "post": { "tags": [ "User Information" ], "summary": "unblock", "description": "Resumes data collection for a specific user, and ends a previous `block` on data collection. This will **not** restore any of data that was deleted by the previous `block` call.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "type": "string", "description": "The `userId` to unblock data collection for. **Required unless you use** `deviceId`. See below for details." }, "deviceId": { "type": "string", "description": "The `deviceId` to unblock data collection for. **Required if no** `userId`.\nA deviceId `block` or `unblock` call will only work for devices where a user has not logged-in on the device. If a user has logged-in on the device before, you must use `userId` with the `block` or `unblock` API calls." }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=getMessage": { "get": { "tags": [ "Messages" ], "summary": "getMessage", "description": "Gets information about a message. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "id", "in": "query", "description": "The numeric message ID.", "required": true, "schema": { "type": "number", "format": "integer" } }, { "name": "includeDrafts", "in": "query", "description": "Include drafts and unpublished changes. Default: `false`.\n", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return details about a message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].message": { "type": "object", "description": "A message object.", "properties": { "id": { "type": "integer", "description": "The message ID." }, "campaignID": { "type": "integer", "description": "The id for the campaign the message is a part of (if applicable)." }, "campaignName": { "type": "string", "description": "The name for the campaign the message is a part of (if applicable)." }, "abTestIds": { "type": "integer", "description": "The id for the A/B tests this message is a part of (if any)." }, "name": { "type": "string", "description": "The name of the message." }, "active": { "type": "boolean", "description": "Whether the message is running in production." }, "state": { "type": "string", "description": "The current status of the message, e.g. active, inactive, finished." }, "created": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was created." }, "updated": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was last updated in Leanplum." }, "scheduledTime": { "type": "number", "description": "Unix timestamp for the scheduled date and time, if message is scheduled." }, "finished": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was finished (optional)." }, "messageType": { "type": "string", "description": "The type of the message. (e.g. Push Notification, Interstitial, etc.)" }, "messageLimits": { "type": "string", "description": "The delivery limits for this message (if any)." }, "localTriggers": { "type": "string", "description": "The trigger event(s) for a locally triggered message, such as an in-app message." }, "serverTriggers": { "type": "string", "description": "The trigger event(s) for a server-triggered message, such as an email or push notification." }, "targetingSticky": { "type": "boolean", "description": "Whether this message's target is sticky (magnet button)." } } } } } } } } }, "deprecated": false } }, "/api?action=getMessages": { "get": { "tags": [ "Messages" ], "summary": "getMessages", "description": "Gets information about all the messages for a given app. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "includeDrafts", "in": "query", "description": "Include drafts and unpublished changes. Default: `false`.\n", "required": false, "schema": { "type": "boolean" } }, { "name": "recent", "in": "query", "description": "Only return information about active or recently finished messages. Default: `true`.\n", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return a list of messages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].messages": { "type": "array", "description": "A list of message objects.", "items": {} }, "response[].messages[]": { "type": "object", "description": "A message object.", "properties": { "id": { "type": "integer", "description": "The message ID." }, "campaignID": { "type": "integer", "description": "The id for the campaign the message is a part of (if applicable)." }, "campaignName": { "type": "string", "description": "The name for the campaign the message is a part of (if applicable)." }, "abTestIds": { "type": "integer", "description": "The id for the A/B tests this message is a part of (if any)." }, "name": { "type": "string", "description": "The name of the message." }, "active": { "type": "boolean", "description": "Whether the message is running in production." }, "state": { "type": "string", "description": "The current status of the message, e.g. active, inactive, finished." }, "created": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was created." }, "updated": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was last updated in Leanplum." }, "scheduledTime": { "type": "number", "description": "Unix timestamp for the scheduled date and time, if message is scheduled." }, "finished": { "type": "number", "format": "float", "description": "Unix timestamp of when the message was finished (optional)." }, "messageType": { "type": "string", "description": "The type of the message. (e.g. Push Notification, Interstitial, etc.)" }, "messageLimits": { "type": "string", "description": "The delivery limits for this message (if any)." }, "localTriggers": { "type": "string", "description": "The trigger event(s) for a locally triggered message, such as an in-app message." }, "serverTriggers": { "type": "string", "description": "The trigger event(s) for a server-triggered message, such as an email or push notification." }, "targetingSticky": { "type": "boolean", "description": "Whether this message's target is sticky (magnet button)." } } } } } } } } }, "deprecated": false } }, "/api?action=getUnsubscribeCategories": { "get": { "tags": [ "Messages" ], "summary": "getUnsubscribeCategories", "description": "Gets information about all the email subscription categories for a given app. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } } ], "responses": { "default": { "description": "A successful response will return a list of email subscription categories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].categories": { "type": "array", "description": "A list of email subscription categories.", "items": {} }, "response[].categories[]": { "type": "object", "properties": { "id": { "type": "integer", "description": "The email category ID. Can be passed to [setUserAttributes](#post_api-action-setuserattributes) as the `unsubscribeCategoriesToAdd` parameter to unsubscribe a user or `unsubscribeCategoriesToRemove` parameter to re-subscribe a user from that category.\n" }, "name": { "type": "string", "description": "The name of the email category." }, "description": { "type": "string", "description": "The description of the email category." } } } } } } } } }, "deprecated": false } }, "/api?action=sendMessage": { "post": { "tags": [ "Messages" ], "summary": "sendMessage", "description": "Sends a message (typically a push notification) to one device or user. You must provide a `deviceId` and/or a `userId`. If `deviceId` is provided, the message will be sent to the corresponding device only; if only `userId` is provided, the message will be sent to all devices of the user with specified `userId`. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below).\n\nMessages are queued, so they will be sent after the request completes.\n\nThis method requires your production API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId", "messageId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "messageId": { "description": "The ID of the message, found in the URL when viewing a message (e.g. `www.leanplum.com/dashboard#/{APP_ID}/messaging/{MESSAGE_ID}`.\n", "type": "number", "format": "integer" }, "values": { "description": "A JSON object of key-value pairs to override template variables used in the message. See below for example.\n", "type": "string", "format": "object" }, "force": { "description": "Whether to send the message regardless of whether the user meets the targeting criteria. Default: `false`.\n", "type": "boolean", "default": false }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateNever`.\n", "default": "CreateNever", "type": "string", "enum": [ "CreateIfNeeded", "CreateNever" ] } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=addAndroidNotificationChannel": { "post": { "tags": [ "Messages" ], "summary": "addAndroidNotificationChannel", "description": "Creates new notification channels and updates existing ones. Updateable parameters include channel name, description, and default. This method requires your development API `clientKey`.\n\n> Leanplum will not interfere with any channel defined directly in your app code or by other mobile marketing providers. For instance, if your app has both a \u201cPromotions\u201d channel and a \u201cTransactional\u201d channel, but your marketer should only have access to Promotions, then you should only send that channel to Leanplum.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "id", "name", "importance" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "id": { "type": "string", "description": "The channel ID. Also used when updating existing channels." }, "name": { "type": "string", "description": "The human-readable name that will appear on the Leanplum dashboard (e.g. Promotions, Transactional, etc.). Should be distinguishable from all other channel names." }, "importance": { "type": "number", "format": "integer", "description": "Sets the importance of all notifications in the channel, which determines how much the channel can interrupt the user. The default is 3: notifications will show everywhere, make noise, but does not visually intrude. For more, see the [Android documentation](https://developer.android.com/guide/topics/ui/notifiers/notifications.html#Priority).\n", "default": 3 }, "description": { "type": "string", "description": "The user-visible description of this channel." }, "groupId": { "type": "string", "description": "See Android docs here." }, "enableLights": { "type": "boolean", "description": "Whether to enable lights." }, "lightColor": { "type": "number", "format": "integer", "description": "See Android docs for [available colors](https://developer.android.com/reference/android/graphics/Color.html)." }, "enableVibration": { "type": "boolean", "description": "Whether to enable vibration." }, "vibrationPattern": { "type": "array", "items": { "type": "number", "format": "long" }, "description": "See Android docs here." }, "lockscreenVisibility": { "type": "number", "format": "integer", "description": "See Android documentation [here](https://developer.android.com/reference/android/app/Notification.html#VISIBILITY_PRIVATE)." }, "bypassDnd": { "type": "boolean", "description": "See Android docs here." }, "showBadge": { "type": "boolean", "description": "Whether to show badge." }, "sound": { "type": "string", "description": "URI of sound file, which must be stored locally on the device. See Andoroid Docs here." }, "default": { "type": "boolean", "description": "This is a Leanplum parameter, indicating whether this channel should be the default channel referenced in the dashboard. Leanplum automatically defines the first channel you create as the \u201cdefault\u201d channel, preventing the dashboard user from having to manually choose a channel for every campaign." } } } } }, "description": "JSON request body with variables and values.", "required": true }, "responses": { "default": { "description": "The response will indicate whether or not the channel was created successfully.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].channelCreated": { "type": "boolean", "description": "Whether or not channel creation was successful." }, "response[].channelId": { "type": "string", "description": "The channel ID. Same as the `id` passed in the call.", "default": "12345" }, "response[].channelUpdated": { "type": "boolean", "description": "True if channel was updated successfully.", "default": false }, "response[].name": { "type": "string", "description": "The human-readable name that will appear on the Leanplum dashboard (e.g. Promotions, Transactional, etc.). Should be distinguishable from all other channel names." }, "response[].importance": { "type": "integer", "description": "The importance of all notifications in this channel." } } } } } } }, "deprecated": false } }, "/api?action=getAndroidNotificationChannels": { "get": { "tags": [ "Messages" ], "summary": "getAndroidNotificationChannels", "description": "Gets all Android notification channels defined in Leanplum and their associated settings. No additional arguments are required. This method requires your production API `clientKey`.\n\nThis method requires your production API `clientKey`.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Production key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_PROD_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } } ], "responses": { "default": { "description": "Returns the Android notification channels you have defined in Leanplum and their associated settings. Note \u2014 an HTTP status of 200 does not guarantee the request was processed successfully. Pay close attention to `response[].warning` and `response[].error`; if returned with a message, the request may have been skipped or ignored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[]": { "type": "array", "description": "The response array.", "items": { "type": "object" } }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].notificationChannels": { "type": "array", "description": "Contains the name, importance, id, and other settings of all Android notification channels defined in Leanplum.", "items": { "type": "object", "properties": { "importance": { "type": "integer", "default": 2 }, "name": { "type": "string", "default": "Promotional" }, "id": { "type": "string", "description": "The channel id.", "default": "abcde" } } } } } } } } } }, "deprecated": false } }, "/api?action=deleteAndroidNotificationChannel": { "post": { "tags": [ "Messages" ], "summary": "deleteAndroidNotificationChannel", "description": "Permanently removes an Android notification channel from Leanplum. This method requires your development API `clientKey`.\n\n**Note** \u2014 You cannot delete the channel that is defined as default (unless it is the only channel). To delete the default channel, mark another channel as default first.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "channelId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "channelId": { "description": "The ID of the channel you want to delete permanently. Note - this is the same as the `id` parameter in the `addAndroidNotificationChannel` method.", "type": "string" } } } } }, "description": "JSON request body with variables and values.", "required": true }, "responses": { "default": { "description": "Response indicates whether channel deletion was successful and returns the channel id of the deleted channel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].channelDeleted": { "type": "boolean", "description": "True if channel was deleted successfully." }, "response[].channelId": { "type": "string", "description": "The channel id. (Same as `id` parameter in addAndroidNotificationChannel method.)", "default": "12345" } } } } } } }, "deprecated": false } }, "/api?action=getAbTest": { "get": { "tags": [ "A/B Tests" ], "summary": "getAbTest", "description": "Gets information about an A/B test. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "id", "in": "query", "description": "The numeric A/B test ID.", "required": true, "schema": { "type": "number", "format": "integer" } }, { "name": "includeDrafts", "in": "query", "description": "Include drafts and unpublished changes. Default: `false`.\n", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return details about an A/B test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].abTest": { "type": "object", "description": "An A/B test object.", "properties": { "id": { "type": "integer", "description": "The A/B test ID." }, "name": { "type": "string", "description": "The name of the A/B test." }, "active": { "type": "boolean", "description": "Whether the A/B test is running in production." }, "created": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was created." }, "updated": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was last updated." }, "finished": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was finished (optional)." }, "chosenVariant": { "type": "number", "format": "float", "description": "The id number of the variant you selected as the winner of the A/B test (optional)." }, "targetingSticky": { "type": "boolean", "description": "Whether the targeting for the test was sticky (magnet button on)." }, "state": { "type": "string", "description": "The current status of the A/B test, e.g. active, inactive, finished." }, "variants": { "type": "array", "description": "A list of variant objects for the A/B test.", "items": {} }, "variants[].id": { "type": "integer", "description": "The ID of the variant." }, "variants[].name": { "type": "string", "description": "The name of the variant." }, "variants[].percent": { "type": "number", "format": "float", "description": "The percentage of new users to allocate to this variant." }, "variants[].variables": { "type": "array", "description": "A list of any variables in the test.", "items": {} }, "variants[].variables[].name": { "type": "string", "description": "The name of the variable being tested." }, "variants[].variables[].value": { "type": "string", "description": "The variable value assigned to this variant." } } }, "response[].abTest.details": { "type": "object", "description": "Contains info about the users who created/last updated the test." }, "response[].abTest.details.publishedBy": { "type": "string", "description": "The username or email address of the Leanplum user who published the test." }, "response[].abTest.details.createdBy": { "type": "string", "description": "The username or email address of the Leanplum user who created the test." } } } } } } }, "deprecated": false } }, "/api?action=getAbTests": { "get": { "tags": [ "A/B Tests" ], "summary": "getAbTests", "description": "Gets information about A/B tests. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "includeDrafts", "in": "query", "required": false, "description": "Include drafts and unpublished changes. Default: `false`.\n", "schema": { "type": "boolean" } }, { "name": "recent", "in": "query", "required": false, "description": "Only return information about active or recently finished A/B tests. Default: `true`.\n", "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return a list of A/B tests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].abTests": { "type": "array", "description": "A list of A/B test objects.", "items": {} }, "response[].abTests[]": { "type": "object", "description": "An A/B test object.", "properties": { "id": { "type": "integer", "description": "The A/B test ID." }, "name": { "type": "string", "description": "The name of the A/B test." }, "active": { "type": "boolean", "description": "Whether the A/B test is running in production." }, "created": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was created." }, "updated": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was last updated." }, "finished": { "type": "number", "format": "float", "description": "Unix timestamp of when the A/B test was finished (optional)." }, "chosenVariant": { "type": "number", "format": "float", "description": "The id number of the variant you selected as the winner of the A/B test (optional)." }, "targetingSticky": { "type": "boolean", "description": "Whether the targeting for the test was sticky (magnet button on)." }, "state": { "type": "string", "description": "The current status of the A/B test, e.g. active, inactive, finished." }, "variants": { "type": "array", "description": "A list of variant objects for the A/B test.", "items": {} }, "variants[].id": { "type": "integer", "description": "The ID of the variant." }, "variants[].name": { "type": "string", "description": "The name of the variant." }, "variants[].percent": { "type": "number", "format": "float", "description": "The percentage of new users to allocate to this variant." }, "variants[].variables": { "type": "array", "description": "A list of any variables in the test.", "items": {} }, "variants[].variables[].name": { "type": "string", "description": "The name of the variable being tested." }, "variants[].variables[].value": { "type": "string", "description": "The variable value assigned to this variant." } } } } } } } } }, "deprecated": false } }, "/api?action=getVariant": { "get": { "tags": [ "A/B Tests" ], "summary": "getVariant", "description": "Gets information about an A/B test variant. This method requires your content read-only API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Content Read-only key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_CONTENT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "id", "in": "query", "description": "The numeric variant ID.", "required": true, "schema": { "type": "number", "format": "integer" } }, { "name": "includeDrafts", "in": "query", "description": "Include drafts and unpublished changes. Default: `false`.\n", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return details about a variant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].variant": { "type": "object", "description": "A variant object.", "properties": { "id": { "type": "integer", "description": "The ID of the variant." }, "name": { "type": "string", "description": "The name of the variant." }, "percent": { "type": "number", "format": "float", "description": "The percentage of new users to allocate." }, "variables": { "type": "array", "description": "A list of any variables in the test.", "items": {} }, "variables[].name": { "type": "string", "description": "The name of the variable in the test." }, "variables[].value": { "type": "string", "description": "The variable value assigned to this variant." } } } } } } } } }, "deprecated": false } }, "/api?action=getVars": { "get": { "tags": [ "Files and Variables" ], "summary": "getVars", "description": "Gets the variable values for the current user or device. If the user/device does not exist, the API request is skipped and a warning will be returned. You can modify this behavior with the `createDisposition` option (see below). To see default variable values, use the `includeDefaults` parameter.\n\nThis method requires your production API `clientKey`.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Production key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_PROD_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "createDisposition", "in": "query", "required": false, "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateNever`.\n", "schema": { "type": "string", "enum": [ "CreateIfNeeded", "CreateNever" ], "default": "CreateNever" } }, { "name": "userId", "in": "query", "description": "The current user ID. Required unless using device ID. You can set this to whatever you use at your company for user IDs. Leave it blank to use the device ID.\n", "required": true, "schema": { "type": "string" } }, { "name": "deviceId", "in": "query", "description": "The device ID for which to retrieve the variables.\n", "required": false, "schema": { "type": "string" } }, { "name": "devMode", "in": "query", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "schema": { "type": "boolean", "default": false } }, { "name": "includeDefaults", "in": "query", "description": "Whether to include default ('defaults in code') values in output. Default: `true`.\n", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "default": { "description": "A successful request will return a response array with an object that has a success value set to true, and no error or warning object. It will also include variables, messages and other details relevant to that user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "description": "Response object for the API action.", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].vars": { "type": "object", "description": "Key/value pairs for variables.", "properties": { "varName": { "type": "string", "description": "The value of the variable `varName`." } } }, "response[].variants": { "type": "array", "description": "List of variants that the user() belongs to.", "items": {} }, "response[].variants[].id": { "type": "number", "description": "ID of the variant." } } } } } } }, "deprecated": false } }, "/api?action=setVars": { "post": { "tags": [ "Files and Variables" ], "summary": "setVars", "description": "Sets the list of variables to be used in the Leanplum content management system. This method requires your development API `clientKey`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "vars" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "vars": { "type": "string", "format": "object", "description": "A JSON-encoded representation of the variables. Variable values can be strings, numbers, booleans, arrays, or objects.\n\nExample: `{ \"message\": \"hello world!\" }`\n" }, "deviceId": { "type": "string", "description": "If the deviceId is specified, file variables will be tagged with the current version of the app running on that device." } } } } }, "description": "JSON request body with variables and values.", "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=deleteVars": { "post": { "tags": [ "Files and Variables" ], "summary": "deleteVars", "description": "Deletes the list of variables from the Leanplum content management system. This method requires your development API `clientKey`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "vars" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "vars": { "type": "array", "description": "A list of variables to be removed.", "items": { "type": "string", "description": "The variable name.", "default": "variableName" } } } } } }, "required": true }, "responses": { "default": { "description": "Returns the status and a list of variables that were deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].variablesRemoved": { "type": "array", "description": "A list of variables that were removed.", "items": { "type": "string" } } } } } } } }, "deprecated": false } }, "/api?action=downloadFile": { "get": { "tags": [ "Files and Variables" ], "summary": "downloadFile", "description": "Redirects to a file uploaded to the Leanplum dashboard (the File tab). Must be the only API method in a batch. This method requires your production API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Production key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_PROD_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "filename", "in": "query", "description": "The name of the file to download.", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "A successful request will redirect to the file and begin a download." } }, "deprecated": false } }, "/api?action=uploadFile": { "post": { "tags": [ "Files and Variables" ], "summary": "uploadFile", "description": "Uploads up to 16 files or 50 MB at a time to use in the File picker and File tab of the Leanlum dashboard. This method requires your development API `clientKey`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "data", "file{k}" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "data": { "description": "A JSON array-encoded string representing each file's metadata. Used when uploading multiple files at once.", "type": "array", "items": { "type": "object", "required": [ "filename", "size" ], "properties": { "filename": { "type": "string", "description": "The filename of the file being uploaded relative to the application." }, "size": { "type": "integer", "description": "The size of the file in bytes." }, "hash": { "type": "string", "description": "To be used when supplying the data parameter. The MD5 hash representing the file. Used to detect changes to files in the SDK in Development Mode." } } } }, "file{k}": { "type": "string", "format": "binary", "description": "Supply if `data` is also supplied. The file data to be uploaded for file \"k\", where \"k\" is based on the order of the metadata in `data[]` (0-based). The first metadata item in `data[]` will be matched with `file0`, the second with `file1`, etc. There should be one file uploaded per entry in data." }, "filename": { "type": "string", "description": "Supply if and only if `data` is not supplied. The filename of the file being uploaded relative to the application." }, "file": { "description": "Supply if and only if `data` is not supplied. The file data to be uploaded.", "type": "string", "format": "binary" }, "size": { "description": "Supply if and only if `data` is not supplied. The size of the file in bytes.", "type": "number", "format": "integer" }, "hash": { "description": "Supply if and only if `data` is not supplied. The MD5 hash representing the file. Used to detect changes to files in the SDK in Development Mode.", "type": "string" } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=addPostback": { "post": { "tags": [ "Export Data" ], "summary": "addPostback", "description": "Adds a postback rule to be triggered by certain Leanplum message or A/B test events. The maximum number of postbacks allowed is three per app. This method requires your data export API `clientKey`. \n\nSee `type` and `channels` below for all possible events that can trigger postbacks. To see what values can be returned by the resulting POST request, see `postbackUrl` with an example template below. \n\n> **Postback retry policy:** If your app is unresponsive, Leanplum's request will timeout in 30 seconds. If the error code is 5xx, we will retry up to 9 more times with exponential backoff, starting from 1 hour, up to 10 hours. If all 10 times fail, the data is lost.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "clientKey", "apiVersion", "type", "postbackUrl" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Data Export key for your Leanplum App.", "default": "YOUR_DATA_EXPORT_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "type": { "type": "string", "description": "The type of postback to add. There are currently two types.\n * `messageEvents` - Postback triggered by message events. See `channels` below for a list of all the message events that trigger postbacks.\n * `abTestEvents` - Postback triggered by the AB test impression/enter event.\n", "enum": [ "messageEvents" ], "default": "messageEvents" }, "channels": { "type": "array", "description": "The messaging channels that will trigger postbacks \u2014 possible values include `Push Notification`, `Email`, and `In-app Message`. For example, this ...`&channels=[Push Notification, In-app Message]`... would activate postbacks for push and in-app message events only. If no channels are set, all three channels will trigger postbacks by default.\n\nSee below for a list of all the events that will trigger postbacks (by channel).\n * Push Notification \u2014 Sent, Open, Held Back\n * Email \u2014 Sent, Deferred, Delivered, Bounce, Open, Click, Marked as spam, Dropped, Unsubscribe, Held Back\n * In-app Message (events by template):\n * All templates \u2014 View, held back.\n * Center Popup, Confirm, Interstitial \u2014 Accept\n * Rich interstitial \u2014 Select Button 1, Select Button 2\n * Satisfaction Survey \u2014 Submit\n * Banner \u2014 Select\nNote that you cannot specify which specific events trigger postbacks, however, you can ignore certain events on your end if you prefer.\n", "items": {} }, "postbackUrl": { "type": "string", "description": "The URL template to post after the trigger event occurs. This should go to the endpoint you are trying to send the postback data to. The template uses the same curly brace format as templated values on the dashboard. You can include any of the values below in your URL template, depending on what info you are interested in. \n\nPossible values for all postback events\n * `User ID` \u2014 The user ID that triggered the postback.\n * `Device ID` \u2014 The device ID that triggered the postback.\n * `Trigger time` \u2014 The time in milliseconds at which the postback was triggered. The time can be a time in the past if the triggering event occurred in the past.\n\nPossible message event values\n * `Message ID` \u2014 The message ID that triggered the postback.\n * `Message event` \u2014 The message event that triggered the postback (e.g. Send, Open).\n * `Message channel` \u2014 The channel of the message (push, email, or in-app message).\n * `Template name` \u2014 The template name of the in-app message. Returns an empty string for non-in-app messages.\n * `Parameters` \u2014 All the parameters associated with the event when it is triggered. For example, an email\u2019s Click event will include the URL clicked and the index of the URL. `parameters` are in JSON format, and all parameter values are URL encoded.\n\nPossible A/B test event values\n * `AB test ID` \u2014 The ID of the A/B test the user entered into.\n * `Variant ID` \u2014 The ID of the variant group the user was sorted into.\n\nSee below for an example URL template with all possible values.\n" } } } } }, "description": "The request body.", "required": true }, "responses": { "default": { "description": "A successful response will return the ID of the new postback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].postbackId": { "type": "integer", "description": "The ID of the newly created postback." } } } } } } }, "deprecated": false } }, "/api?action=listPostbacks": { "get": { "tags": [ "Export Data" ], "summary": "listPostbacks", "description": "List current postback rules. This method requires your data export API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } } ], "responses": { "default": { "description": "A successful response will return a list of postbacks.", "content": { "application/json": { "schema": { "type": "object", "description": "test.", "properties": { "response": { "type": "array", "items": {} }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].postbacks": { "type": "array", "description": "The list of active postbacks for the given app.", "items": {} }, "response[].postbacks[]": { "type": "object", "properties": { "postbackId": { "type": "integer", "description": "The ID of the postback." }, "type": { "type": "string", "description": "The type of the postback." }, "postbackUrl": { "type": "string", "description": "The URL template of the postback." } } } } } } } } }, "deprecated": false } }, "/api?action=deletePostback": { "post": { "tags": [ "Export Data" ], "summary": "deletePostback", "description": "Deletes a particular postback. This method requires your data export API `clientKey`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "postbackId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Data Export key for your Leanplum App.", "default": "YOUR_DATA_EXPORT_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "postbackId": { "type": "number", "format": "integer", "description": "The ID of the postback to delete." } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } }, "/api?action=exportData": { "get": { "tags": [ "Export Data" ], "summary": "exportData", "description": "Exports raw data to downloadable files. Data is split into roughly 256 MB files, and is not necessarily ordered. Exports can be made in JSON or CSV format. For JSON format, each file contains 1 line per session, with each session JSON-encoded. For CSV format, data is split into separate files for sessions, states, events, event parameters, and user attributes. \n\n> Note that for daily exports, you may see some variation in sessions data results. This is because sessions data can come in up to 8 days after a user's last interaction with your app. \n\nExport files are automatically deleted 24 hours after export occurs. Data becomes available to export every 2 hours, and only for complete sessions. You cannot export data that has become available more than 60 days ago. You may only export data 24 times per day. Exports with invalid arguments do not count towards this limit.\n\nUse [getExportResults](#get_api-action-getexportresults) with the returned `jobId` to get the results.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "startDate", "in": "query", "description": "First date in range to include in PDT/PST (format: YYYYmmdd). Example: `20140223`.\n", "required": true, "schema": { "type": "string" } }, { "name": "exportFormat", "in": "query", "description": "The format to export data. Can be either `json` or `csv`. Default: `json`.\n", "required": false, "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "description": "Last date in range to include in PDT/PST (format: YYYYmmdd). Defaults to startDate if not provided. Example: `20140223`.\n", "required": false, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "First time (when data became available) to include (seconds since midnight UTC on January 1, 1970). If not provided, accepts all times before endTime, or all times if endTime is also not provided. The main use is to set this to the last time you exported data to only get the new data since your last export.\n", "required": false, "schema": { "type": "number" } }, { "name": "endTime", "in": "query", "description": "Last time (when data became available) to include (seconds since midnight UTC on January 1, 1970). If not provided, accepts all times after startTime, or all times if startTime is also not provided.", "required": false, "schema": { "type": "number" } }, { "name": "callbackUrl", "in": "query", "description": "URL to POST a response to when the export completes. The response is the response format of `getExportResults`.\n", "required": false, "schema": { "type": "string" } }, { "name": "s3BucketName", "in": "query", "description": "The name of an AWS S3 bucket to copy exported files to.", "required": false, "schema": { "type": "string" } }, { "name": "s3AccessId", "in": "query", "description": "The AWS Access ID used to authenticate to S3. Required if `s3BucketName` is set.\n", "required": false, "schema": { "type": "string" } }, { "name": "s3AccessKey", "in": "query", "description": "The AWS Secret Access Key used to authenticate to S3. Required if `s3BucketName` is set.\n", "required": false, "schema": { "type": "string" } }, { "name": "s3ObjectPrefix", "in": "query", "description": "An optional prefix of files to write to S3. Example: `dirname/` to write files to a directory within the S3 bucket.\n", "required": false, "schema": { "type": "string" } }, { "name": "compressData", "in": "query", "description": "An option to compress the data. Only works when uploading to S3. If set to true, the files will be compressed using gzip before being uploaded.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "A successful response will return the ID of the export job.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].jobId": { "type": "string", "description": "The job ID of the pending export job, if data matching the supplied arguments is available. Use [getExportResults](#get_api-action-getexportresults) with this `jobId` to get the results.\n" } } } } } } }, "deprecated": false } }, "/api?action=exportReport": { "get": { "tags": [ "Export Data" ], "summary": "exportReport", "description": "Exports statistics for an A/B test, message, bookmarked report, or user activity in your app (as in the Analytics tab of the dashboard) over specified period of time. Report data becomes available to export every 2 hours, and only for complete sessions. You may only export report data 100 times per day per app. Exports with invalid arguments do not count towards the limit.\n\nThis method requires your data export API `clientKey`.\n\nUse [getExportResults](#get_api-action-getexportresults) with the returned `jobId` to get the results.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "startDate", "in": "query", "description": "First date in range to include in PDT/PST (format: YYYYmmdd). Example: `20150708`.\n", "required": true, "schema": { "type": "string" } }, { "name": "dataType", "in": "query", "description": "The type of the id provided. It can be either:\n * `UserActivity` for general statistics about your app\n * `AbTestResults` for stats about an A/B test\n * `MessageResults` for stats about a message, or\n * `BookmarkedReport` for stats about a bookmarked report.\n\nIf you choose `AbTestResults`, `MessageResults`, or `BookmarkedReport`, you must also supply the corresponding `abTestId`, `messageId`, or `bookmarkName`.\n", "required": true, "schema": { "type": "string", "enum": [ "UserActivity", "AbTestResults", "MessageResults", "BookmarkedReport" ] } }, { "name": "endDate", "in": "query", "description": "Last date in range to include in PDT/PST (format: YYYYmmdd). Defaults to startDate if not provided. Example: `20150708`.\n", "required": false, "schema": { "type": "string" } }, { "name": "abTestId", "in": "query", "description": "Supply if any only if `dataType` is set to `AbTestResults`.\n", "required": false, "schema": { "type": "number" } }, { "name": "messageId", "in": "query", "description": "Supply if and only if the `dataType` is set to `MessageResults`.\n", "required": false, "schema": { "type": "number" } }, { "name": "bookmarkName", "in": "query", "description": "Supply if and only if the `dataType` is set to `BookmarkedReport`. This is the name of the report, as it appears in your Analytics tab.\n", "required": false, "schema": { "type": "string" } }, { "name": "eventNames", "in": "query", "description": "A JSON-encoded array containing names of the events to be included in the report. Example: `[\"Add to cart\", \"Purchase\"]`\n", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "default": { "description": "A successful response will return the ID of the export job.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].jobId": { "type": "string", "description": "The job ID of the pending export job, if data matching the supplied arguments is available. Use [getExportResults](#get_api-action-getexportresults) with this `jobId` to get the results.\n" } } } } } } }, "deprecated": false } }, "/api?action=exportUser": { "get": { "tags": [ "Export Data" ], "summary": "exportUser", "description": "Retrieves attributes for the current user. This method requires your data export API `clientKey`.", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "userId", "in": "query", "required": true, "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "schema": { "type": "string", "default": "hfarnsworth" } }, { "name": "deviceId", "in": "query", "required": false, "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "schema": { "type": "string" } } ], "responses": { "default": { "description": "A successful request will return a map of the user's attributes, events and states.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].userId": { "type": "string", "default": "hfarnsworth@planetexpress.com", "description": "The ID of the user that was exported. Not included if the user was not found." }, "response[].userAttributes": { "description": "A map of user attribute keys to values. Example: `{\"gender\":\"F\",\"age\":21}`.\n", "type": "object" }, "response[].events": { "type": "object", "properties": { "eventName": { "type": "object", "description": "A map of lifetime event data for the event given by eventName.", "properties": { "count": { "type": "integer", "description": "Lifetime occurrences for the event." }, "value": { "type": "number", "format": "float", "description": "Lifetime value for eventName." }, "firstTime": { "type": "integer", "description": "Time that the event first occurred, in seconds since midnight UTC on January 1, 1970." }, "lastTime": { "type": "integer", "description": "Time that the event last occurred, in seconds since midnight UTC on January 1, 1970." } } } } }, "response[].states": { "type": "object", "properties": { "stateName": { "type": "object", "description": "A map of lifetime state data for the state given by stateName.", "properties": { "count": { "type": "integer", "description": "Lifetime occurrences for eventName." }, "firstTime": { "type": "integer", "description": "Time that the state first occurred, in seconds since midnight UTC on January 1, 1970." }, "lastTime": { "type": "integer", "description": "Time that the state last occurred, in seconds since midnight UTC on January 1, 1970." } } } } }, "response[].created": { "type": "number", "format": "float", "description": "The time at which the user was created, in seconds since midnight UTC on January 1, 1970." }, "response[].lastActive": { "type": "number", "format": "float", "description": "The time at which the user was last active, in seconds since midnight UTC on January 1, 1970." }, "response[].totalSessions": { "type": "number", "format": "integer", "description": "The total number of sessions that a user has had in their lifetime." }, "response[].timeSpentInApp": { "description": "The total number of seconds spent in the app in the user's lifetime.", "type": "number", "format": "float" }, "response[].locale": { "description": "The current locale the user is in. E.g. `en_US`.\n", "type": "string" }, "response[].country": { "description": "The country the user is in, specified by [ISO 2-letter code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). E.g. `US` for United States. Set to `(detect)` to detect the country based on the IP address of the user.\n", "type": "string" }, "response[].region": { "description": "The region (state) the user is in. E.g. `ca` for California. Set to `(detect)` to detect the region based on the IP address of the user.\n", "type": "string" }, "response[].city": { "description": "The city the user is in. E.g. `San Francisco`. Set to `(detect)` to detect the city based on the IP address of the user.\n", "type": "string" }, "response[].location": { "description": "The location (latitude/longitude) of the user. E.g. `37.775,-122.4183`. Set to `(detect)` to detect the location based on the IP address of the user.\n", "type": "string" }, "response[].locationAccuracyType": { "description": "The type of location that is provided (IP, CELL, or GPS). Default: `IP`.\n", "type": "string" }, "response[].timezone": { "description": "The timezone abbreviation for the user. See [list of timezone abbreviations](http://en.wikipedia.org/wiki/List_of_time_zone_abbreviations).\n", "type": "string" }, "response[].timezoneOffsetSeconds": { "description": "The timezone offset from GMT in seconds.", "type": "number", "format": "integer" }, "response[].unsubscribeChannels": { "type": "array", "description": "A list of messaging channels (e.g. `Email`) the user is unsubscribed from.\n", "items": { "type": "string", "default": "Email" } }, "response[].unsubscribeCategories": { "type": "array", "description": "A list of email categories the user is unsubscribed from.", "items": {} }, "response[].unsubscribeCategories[].id": { "type": "integer", "description": "The email category ID. Can be passed to [setUserAttributes](#post_api-action-setuserattributes) as the `unsubscribeCategoriesToAdd` parameter to unsubscribe a user or `unsubscribeCategoriesToRemove` parameter to re-subscribe a user from that category.\n" }, "response[].unsubscribeCategories[].name": { "type": "string", "description": "The name of the email category." }, "response[].devices": { "type": "array", "description": "A list of device objects associated with this user.", "items": {} }, "response[].devices[]": { "type": "object", "properties": { "deviceId": { "description": "The unique ID for the device.", "type": "string" }, "appVersion": { "description": "The version of the app used on this device. E.g. `2.0.1`.\n", "type": "string" }, "systemName": { "description": "The name of the OS the current device is running. E.g. `iOS`.\n", "type": "string" }, "systemVersion": { "description": "The version number of the OS the current device is running. E.g. `6.0`.\n", "type": "string" }, "browserName": { "description": "The name of the browser the current device is running. E.g. `Chrome`.\n", "type": "string" }, "browserVersion": { "description": "The version number of the browser the current device is running. E.g. `17.0`.\n", "type": "string" }, "deviceName": { "description": "A human-readable name representing the device.", "type": "string" }, "deviceModel": { "description": "The model name of the device. E.g. `iPad`.\n", "type": "string" }, "iosPushToken": { "description": "The token used for Apple iOS push notifications on this device.", "type": "string" }, "gcmRegistrationId": { "description": "The registration ID used for Google Cloud Messaging push notifications on this device.", "type": "string" }, "webPushSubscription": { "description": "The JSON-encoded subscription used for web push notifications on this device.", "type": "string" } } } } } } } } }, "deprecated": false } }, "/api?action=exportUsers": { "get": { "tags": [ "Export Data" ], "summary": "exportUsers", "description": "Exports multiple user IDs. The export may be executed up to 40 times successfully per day, and this limit resets at 12:00 am PST each calendar day. This method requires your data export API `clientKey`.\n\nUse [getExportResults](#get_api-action-getexportresults) with the returned `jobId` to get the results.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "audienceName", "in": "query", "description": "Export users in a particular audience. Use the audience name as seen on your audience dashboard. If skipped, Leanplum will export all users, unless other filters are applied.\n", "required": false, "schema": { "type": "string" } }, { "name": "abTestId", "in": "query", "description": "Limit export to only users that are in the given A/B test. The output will include the variant ID and name for each user.", "required": false, "schema": { "type": "number", "format": "integer" } }, { "name": "userAttribute", "in": "query", "description": "Export users with a specific attribute set. The export results will include the userId and attribute value for each user. For example, userAttribute `email` would export all email users along with their email addresses.", "required": false, "schema": { "type": "string" } } ], "responses": { "default": { "description": "A successful response will return the ID of the export job.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].jobId": { "type": "string", "description": "The job ID of the pending export job, if data matching the supplied arguments is available. Use [getExportResults](#get_api-action-getexportresults) with this `jobId` to get the results.\n" } } } } } } }, "deprecated": false } }, "/api?action=getExportResults": { "get": { "tags": [ "Export Data" ], "summary": "getExportResults", "description": "Retrieves the result of an export job generated by: `exportData`, `exportReport`, and `exportUsers`. This method requires your data export API `clientKey`.\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Data Export key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DATA_EXPORT_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "jobId", "in": "query", "description": "The export job ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Returns the status and either a list of file URLs that contain the exported data (for `exportData` and `exportUsers`), or JSON in the response body (`exportReport`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object" } }, "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].state": { "type": "string", "description": "Export job state. May be `PENDING`, `RUNNING`, `FAILED`, or `FINISHED`. Once finished, you will get additional data. See more info: [exportData](#section-exportdata-response), [exportUsers](#section-exportusers-response).\n", "enum": [ "PENDING", "RUNNING", "FAILED", "FINISHED" ], "default": "FINISHED" } } } } } } }, "deprecated": false } }, "/api?action=multi": { "post": { "tags": [ "Import Data" ], "summary": "multi (CSV)", "description": "Imports a (potentially large) CSV file with API actions to be executed. The file will be imported asynchronously as a job. Use `getMultiResults` to get the job status. This method requires your development API `clientKey`. See [CSV uploads](/v1/docs/import-user-data-with-a-csv-file-upload) for more on using `multi` to upload user attributes, events, and device attributes.\n\nThe file should contain a header row with the API argument names that are found in the API documentation, such as `userId`, `deviceId`, and `action` (if `defaultAction` is not specified). To indicate nested JSON arguments, use a dot within the column name, such as `userAttributes.Gender`.\n\n```csv\nuserId,userAttributes.Gender,userAttributes.Age\nuser1,Male,25\nuser2,Female,37\n```\n\n> The file is broken into separate API requests that contain batches of 50 actions. Each unique user lookup in a batch is a billable API call. See [billing and costs](./reference#billing) for more.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "apiVersion", "createJob", "gcsBucket", "file" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "createJob": { "description": "Whether to create an asynchronous job to import the data. This is required to be set to `true`.\n", "type": "boolean", "default": true }, "gcsBucket": { "description": "The name of the Google Cloud Storage bucket that contains the CSV file to be imported.", "type": "string" }, "file": { "description": "The Google Cloud Storage object name of the CSV file. The object must be made public to be read by Leanplum's servers, so the filename should be set to something obscure.", "type": "string" }, "defaultAction": { "description": "The default API action to apply across all rows in the CSV file. For example, if the file contains all user attributes to be imported, `defaultAction` should be set to `setUserAttributes`.\n", "type": "string" } } } } }, "required": true }, "responses": { "default": { "description": "A successful response will return a `jobId` and status of `200`. **Note**: an HTTP status of 200 does not guarantee the call was processed successfully. Pay close attention to `response[].warning` and `response[].error`; if returned with a message, the call may have been skipped or ignored.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].jobId": { "type": "string", "description": "The ID of the import job. Pass this `jobId` into [getMultiResults](#get_api-action-getmultiresults) to fetch the job status and results." } } } } } } }, "deprecated": false } }, "/api?action=getMultiResults": { "get": { "tags": [ "Import Data" ], "summary": "getMultiResults", "description": "Gets the status of a multi import job. This method requires your development API `clientKey`.\n\nExample:\n`http://api.leanplum.com/api?action=getMultiResults&appId=APP_ID&clientKey=DEVELOPMENT_KEY&jobId=JOB_ID`\n", "parameters": [ { "name": "appId", "in": "query", "required": true, "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "schema": { "type": "string", "default": "YOUR_APP_ID" } }, { "name": "clientKey", "in": "query", "required": true, "description": "The Development key for your Leanplum App.", "schema": { "type": "string", "default": "YOUR_DEV_KEY" } }, { "name": "apiVersion", "in": "query", "required": true, "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "schema": { "type": "string", "enum": [ "1.0.6" ], "default": "1.0.6" } }, { "name": "jobId", "in": "query", "description": "The ID of the job to query. The job ID is returned by `multi`.\n", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Returns the status and a list of file URLs that contain the individual API responses as documented in the API documentation for the relevant API methods. Each response is represented as a line of JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].state": { "type": "string", "description": "The job state. Either `PENDING`, `RUNNING`, `FINISHED`, or `FAILED`.\n", "enum": [ "PENDING", "RUNNING", "FINISHED", "FAILED" ], "default": "FINISHED" }, "response[].data": { "type": "object", "description": "For finished jobs, contains the job result.", "properties": { "successesCount": { "type": "integer", "default": 10, "description": "The number of API actions that succeeded within the job." }, "failuresCount": { "type": "integer", "default": 0, "description": "The number of API actions that failed within the job." }, "files": { "type": "array", "description": "A list of file URLs that contain the individual API responses as documented in the API documentation for the relevant API methods. Each response is represented as a line of JSON.", "items": { "type": "string", "default": "fileURL" } } } } } } } } } }, "deprecated": false } }, "/api?action=startCampaign": { "post": { "tags": [ "Campaigns" ], "summary": "startCampaign", "description": "Activates a campaign for one device or user. You must provide a `deviceId` and/or a `userId`. If `deviceId` is provided, the campaign top-level actions will be sent to the corresponding device only; if only `userId` is provided, the campaign top-level actions will be sent to all devices of the user with specified `userId`. If the user/device does not exist, sending the actions will be skipped. You can modify this behavior with the `createDisposition` option (see below).\n\nThis method requires your development API `clientKey`.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId", "campaignId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Development key for your Leanplum App.", "default": "YOUR_DEV_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "campaignId": { "description": "The ID of the campaign is found in the URL when viewing a campaign (e.g. `www.leanplum.com/dashboard2/[APP_ID]/composer/[CAMPAIGN_ID]/audience}`). Note that there might be multiple IDs in the URL, the campaign ID is right after `composer/`.\n", "type": "number", "format": "integer" }, "values": { "description": "A JSON object of key-value pairs to override template variables used in the campaign actions. See below for example.\n", "type": "string", "format": "object" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateNever`.\n", "default": "CreateNever", "type": "string", "enum": [ "CreateIfNeeded", "CreateNever" ] } } } } }, "required": true }, "responses": { "default": { "description": "The default response for most API actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response[].success": { "description": "Whether the request was *received*. Verify that the response has neither `warning` or `error` objects to confirm the action was taken. See [here](#responses) for more.", "type": "boolean" }, "response[].warning.message": { "type": "string", "description": "The warning message for the API action, if any." }, "response[].error.message": { "type": "string", "description": "The error message for the API action, if any." } } } } } } }, "deprecated": false } } }, "servers": [ { "url": "https://api.leanplum.com" }, { "url": "http://api.leanplum.com" } ], "components": { "requestBodies": { "Body": { "content": { "application/json": { "schema": { "type": "object", "description": "JSON request body.", "required": [ "appId", "clientKey", "apiVersion", "userId" ], "properties": { "appId": { "description": "The application ID. To find yours, select your app in the navigation column, and click Manage Apps. Then click Keys & Settings.", "default": "YOUR_APP_ID", "type": "string" }, "clientKey": { "description": "The Production key for your Leanplum App.", "default": "YOUR_PROD_KEY", "type": "string" }, "apiVersion": { "description": "The version of the Leanplum API to use. The current version is 1.0.6.", "default": "1.0.6", "type": "string", "enum": [ "1.0.6" ] }, "userId": { "description": "The current user ID. You can set this to whatever your company uses for user IDs. Leave it blank to use the device ID. For more info, see [selecting a user](#selecting-a-user).\n", "default": "hfarnsworth", "type": "string" }, "deviceId": { "description": "A unique ID for the device targeted by the request. You must provide a `deviceId` and/or a `userId`. See [selecting a user](#selecting-a-user).\n", "type": "string" }, "devMode": { "type": "boolean", "description": "Whether the user is in Development Mode, i.e. the user associated with the request is a developer and not a user. This is important for reporting purposes. Default: `false`.\n", "default": false }, "createDisposition": { "description": "The policy that determines whether users are created by the API. Possible values:\n * `CreateIfNeeded` creates a user with the given IDs if one does not already exist.\n * `CreateNever` requires that the user already exists, otherwise the API action is skipped and a warning will be returned.\n\nThe default value for this method is `CreateNever`.\n", "default": "CreateNever", "type": "string", "enum": [ "CreateIfNeeded", "CreateNever" ] } } } } }, "required": true } }, "securitySchemes": { "appIdQuery": { "type": "apiKey", "in": "query", "name": "appId", "description": "The application ID. To find yours, select your app in the navigation column, and click Edit Apps. Under Keys, click Show." }, "clientKeyQuery": { "type": "apiKey", "in": "query", "name": "clientKey", "description": "The client access key. Must be either your production, development, read-only, or data export key, depending on which API method you want to use." } } }, "x-readme": { "proxy-enabled": true } }