NAV Navbar

Overview

SessionM integrates marketing automation and data management capabilities with loyalty marketing to drive personalized customer relationships through the mobile device and across channels.

Central to the SessionM Platform is its collection of REST APIs. Powered by JSON data over HTTP, the APIs support both server-to-server and client-to-server transactions.

For the most part, the SessionM APIs are designed to submit customer-related data to the platform, performing a set of transactions on the data for a specific customer and returning the related results. The operations, or methods, available in each API utilize JSON requests to call a resource's URI and elicit a JSON response.

These responses may confirm that some alteration has been made to the stored resource, and they may provide hypertext links to other related resources or collections of resources. Using HTTP, the kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE.

The platform is driven by rules that define customer actions and trigger outcomes for those actions; many are simple in nature, while others are more subtle and complex. A simple case would be a customer clicking an icon in an application and triggering the display of a message. A more complex case would be performing logical operations to express more complex rules, related to digital engagement, purchase or location data.

These rule sets can be configured within the SessionM Platform via the web-based administrative tool or through a managed service by which SessionM staff handle all configuration work based on client requests.

Prior to implementing any platform APIs, it is important to work with your account representatives to fully understand your desired workflow and outcomes, as these impact the data that is returned in the API responses.

In addition to our comprehensive API set, we offer SDK support to handle the lifecycle around client-to-server communication for actions, eligibility, messaging and analytics. Many clients leverage these native libraries to shorten development cycles and overall level of effort for an integration. For information about the SessionM SDK, please see our SessionM SDK online guide.

If you want to utilize an API for managing the transactions that occur via a Point of Sale system, see our POS API. Note that this API is not designed to be used in conjunction with the SessionM Platform APIs detailed on this site.

Platform Terminology with Respect to APIs

The SessionM Platform is comprised of four basic components when working with APIs:

The APIs

The SessionM Platform provides a set of APIs that make programmatic access to that data possible. It offers services for several types of key, cloud-based marketing data. The APIs themselves are organized into groupings that reflect the primary functions of the system.

The Customers grouping is a collection of APIs that support foundational types of customer data with operations that manage customer profile data with Standard and Custom Profile APIs. In addition, these APIs offer services for authorizing protocols (Authorization Tokens API), managing access tokens for customer logins (Access Tokens API), building hierarchies of related customers (Customer Affiliation API), representing a customer's devices (Devices API) or frequented places (Places API), and, most importantly, the events customers generate with an Events API and Timeline APIs for event streams. This grouping offers an SMS verification API for sending a Short Message Service (SMS) message to a customer in the form of a link to follow or an activation code to apply. And, finally, the this collection contains an API for managing customer data privacy requests (Data Privacy API), which can include requests to forget or export personal data as well as restrict customers from or reinstate customers to loyalty and marketing programs.

The platform's real-time rules engine listens for customer events from a variety of sources. You can define customer actions using these events and their metadata, and then set rules against them to trigger real-time, personalized outcomes.

Rules can be set against the following:

In addition, engagement with customers can also be driven from planned marketing campaigns.

The Audiences grouping includes a Tags API that supports the classification of customers with audience segmentation tags. Each segment can be associated with a variety of rule types, including targeting rules. Tags can be attached to customers, acting as keyword classifiers. They are associated with a counter to indicate the number of times a tag has been assigned.

The Campaigns grouping represents scheduled and targeted customer engagement of any kind, including promotions, display advertising, personalized push notifications or in-app messaging. The grouping includes an API that manages campaigns (Campaigns API) with or without customer IDs. It also includes an API for managing the redemption orders often promoted as part of a campaign, providing clients with a way to track how many times a customer has earned a reward for a specific campaign (Redemptions API). In addition, you can use the Inbox API for sending and managing application inbox notifications for specific customers participating in campaigns or for an organization as a whole.

The Loyalty grouping enables organizations to define actions and incentivize their completion in order to keep customers engaged with long-term and expanding customer loyalty programs. Services manage a variety of entities that are critical to building customer loyalty, including APIs for the following:

Finally, the SessionM Platform offers the Advanced grouping for APIs and procedures that support some complex and generally less common implementation goals. For example, the Lockout and Limiter APIs can be used to develop logic that controls customers’ ability to claim promo codes based on their past activity. In addition, the grouping offers the Model API for retrieving the customer model defined for a specific organization.

Registered Customers and Anonymous (Unregistered) Users

SessionM supports engagement and reporting against the traffic associated with registered customers as well as unregistered, or anonymous, users.

Anonymous users inherit most attributes and abilities of regular registered users with a couple of important differences:

On registration, the anonymous user’s UUID is passed into the Standard Profile API or a customer’s import file. The anonymous UUID becomes SessionM's registered user ID. Any tags, standard or custom attributes, points balances, achievements, devices, ad engagements or reporting metrics associated with the customer is carried over to the persisted, registered customer record.

Single Session Implementations

In order to track individual sessions accurately, SessionM supports an X-Session-Id header and xsid parameter. This header or parameter should be passed in on every request, server-to-server or client-to-server. The value of this header or parameter should be an equivalent enduser session identifier. Validation rules for the identifier values can be configured and enforced. The recommended identifier value is a UUID, ideally format version 1 (RFC 4122) for timestamp debugging.

When an X-Session-Id/xsid implementation is not underway, SessionM approximates session tracking metrics based on request timestamps.

Multiple Session Implementations

Anonymous users interact with client-to-server and server-to-server APIs via the authorization bearer header and JWT access tokens. Additionally, the JWT tokens may be added as an auth_token query parameter value for use across various client-to-server requests.

Client servers may generate their own anonymous JWT tokens. These tokens should be assigned to the visitor for their lifetime or until the visitor registers; a 10 year expiration period (or lifetime) is appropriate. One easy client implementation approach is to set the UUID or JWT token in a non-expiring cookie and read from it each request.

JWT token generation and payload may differ depending on origin but must contain specific claim keys. Every anonymous JWT token must contain a "user" key and a JSON object value containing the following: {“anonymous" : UUID}. The UUID is used to find or create an anonymous user record. The recommended format for timestamp debugging is UUID, version 1 (RFC 4122).

Tokens generated by SessionM are returned via the Authorization Tokens API. These tokens, like client-server generated tokens, contain a "user" key with a JSON object value containing the following: {“anonymous" : UUID}.

Anonymous user records expire after 2 months of inactivity, with TTL reset upon each new session start. If an anonymous ID that links to an expired, purged anonymous user record is requested, it is re-created automatically with the existing anonymous UUID value.

Authentication, Authorization and Security

SessionM APIs operate with state-of-the-art authentication, authorization and security features. The APIs are accessible to engineering and services professionals via server-to-server and client-to-server communication protocols, which allow the platform to unify user actions for improved reporting. Part of this approach includes tracking both anonymous and registered user actions where applicable.

Both server-to-server and client-server communications can use HTTP authorization protocols with authentication tokens. They include:

Following is a sample request made via a Curl command:

▿ Example Request

curl -H "Content-Type: application/json" --data '{"user":{"email":"foo@bar.com"}}' -u
api_key:s2s_api_secret https://api.sessionm.com/priv/v1/apps/:api_key/users

Server-to-Server

Server-to-server communications can use either HTTP basic or HTTP bearer authorization protocols. For the basic protocol, each request must contain an API key and server-to-server API secret supplied by the SessionM Platform; for the bearer protocol, each request must contain an authorization token in an HTTP header. All requests must be made over HTTPS.

As an additional security measure, access to APIs lives behind a basic authentication layer and can be additionally IP-restricted to meet the security requirements of specific client needs. These credentials are always required for server-to-server communication with the SessionM Platform.

In order to begin using any server-to-server APIs, the client must first request an API key and server-to-server API Secret issued from the SessionM Platform. For more information, see Before You Begin.

Client-to-Server

Client-to-server implementations can utilize an HTTP bearer authorization protocol or authorization tokens to ensure secure communication. The HTTP bearer protocol requires each request to contain an authorization token in an HTTP header.

Alternatively, authorization tokens guard all API calls from the client to the server for customer-specific operations. The tokens are issued through a server-to-server call from your organization's server to the SessionM Platform. The token can then be passed as a parameter in a request, as shown below:

▿ Example Request

https://api.sessionm.com/api/v1/apps/:api_key/example?auth_token=v2--
Sd2T8UBqlCGQovVPnsUs4eqwFe0-1i9JV4nq__RWmsA=--
dWM8r8RggUJCToOaiiT6NXmiOipkovvD9HueM_jZECStExtGFkZzVmCUhkdDJe5NQw==

Among other uses, they can be passed down to client browsers or embedded in emails. All authorization tokens have a built-in expiration, which is returned in the response to the request for an authorization token.

Note that the encryption key for the token is per client digital property. This means that it is not possible to use the same token for two different client properties (e.g., the client cannot use the same token for their website and native iOS app). For more information, see Authorization Tokens API.

Using the Authorization Tokens API, you can fetch and validate tokens as well as retrieve tokens along with a standard or custom customer profile. Each call obtains a token that can be used to enable an application to communicate with the platform directly from a client such as a browser. The token can be used with native applications that do not use the SessionM SDK.

Message IDs

When using the SessionM S2S APIs, it is strongly recommended that the client provide a unique Message ID with each request, as follows:

▿ Example HTTP Request Header

GET /path/to/api/endpoint HTTP/1.1
Content-Type: application/json
Message-ID: de305d54-75b4-431b-adb2-eb6b9e546014


Doing so allows a simple way to track messages and also provides a means for supporting idempotent requests. When a request is sent with a Message ID in its HTTP header, that ID becomes associated with the request. It is included in the HTTP header of the accompanying response and can be used to uniquely identify a message within the SessionM Platform.

A request that is sent with a Message ID lists the message processing date in its response. Also, subsequent requests for the same Message ID made within 30 minutes of the original causes a cached response to be re-sent without producing any new changes in state. Replayed requests like this are marked by the ‘Cached-Message’ header being set to 'true’ in the response, as shown below:

▿ Example HTTP Response Header (Existing Message)

HTTP/1.1 200 OK
Content-Type: application/json
...
Message-Id: de305d54-75b4-431b-adb2-eb6b9e546014
Message-Date: Mon, 28 Sep 2015 03:04:15 GMT
Cached-Message: true

Generic Statuses and Errors

When an API method runs, one of the following HTTP response status codes is returned:

Here is an example:

▿ Generic Error Example

{
  "status" : "error",
  "errors" :
  {
    "code" : "requires_registered_user"
  }
}


When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Consider the generic error example shown in the frame right-hand frame. Returned errors can be either method-specific or generic, which is the case for the error above. Any method-specific errors are documented in their associated API document. However, responses that return generic errors may contain a message from the platform indicating any of the following conditions:

Code Reason
INTERNAL_SERVER_ERROR Unexpected SessionM server error occurred.
HTTPS_ONLY HTTPS protocol is required.
INVALID_AUTH_TOKEN Token could not be decrypted; or token has expired.
USER_NOT_FOUND Customer ID or external customer ID not located in the system.
INVALID_API_KEY Wrong API key passed in.
REQUIRES_REGISTERED_USER Similar to USER_NOT_FOUND.
MISSING_DATA Required parameters not passed in.
VALIDATION This catch-all validation error is returned when there is no specific error code.
ACCESS_DENIED Authentication credentials passed in were invalid.
NOT_AVAILABLE Object was found but is unavailable. For example, a campaign not being targeted to a requesting customer.
NOT_FOUND Object does not exist.
ARGUMENT_ERROR Unexpected type or format parameter.

For information on responses that return object-specific errors, see the object's dedicated API.

Note: When developing code that integrates with the SessionM platform, organizations can expect that error codes will not change. This principle ensures that development teams can utilize these error codes to create and communicate error messages that make sense for their implementation, or their customers. Alternatively, it's worth noting that the SessionM messages provided with the codes are available.

Before You Begin

Before you begin using the SessionM APIs, you need to obtain a set of authentication credentials for the web site or application you are integrating. Using these credentials, your site or application can call all of the services available with the SessionM API. Each call to the platform via an API is authenticated by an API key and an S2S API secret.

These credentials are generated when you register your site or application as a digital property of the SessionM Platform. Property types include:

To add a digital property:

  1. Using the account login credentials provided to you from SessionM, log in to the platform from your specified sign-in page.

    The dashboard for the SessionM Platform opens.

    Don't have account credentials? Consult your Customer Success contact at Enterprise-CS@sessionm.com.

  2. Click the Digital Properties module.

    The All Digital Properties page opens.

  3. For a new property, click the Add Digital Property button.The Add Digital Property dialog opens.

  4. Click the appropriate tab for your property, choosing either Browser, iOS App or Android App.

  5. Enter values in the tab's required fields and click the Save button.

    You can now view the API key and S2S API secret by clicking on the property name of your digital property, which is accessible from the All Digital Properties page. These values function as credentials, which persist indefinitely, for all your server-to-server API calls.

After you have established your server-to-server credentials, you can generate a client-to-server token using a server-to-server API call. For more information on obtaining tokens, see Authorization Tokens API.

Customers

The APIs featured in this grouping support foundational types of customer (often called “user” in platform code) data with operations for the following:

Authorization Tokens API

Authorization Tokens are tokens that provide customers limited and temporary access to SessionM APIs. Requiring a SessionM generated token ensures that each SessionM API request is made by an authorized customer. Once the server receives the token, it verifies it for authenticity and then responds to the request.

Tokens offer a few important benefits. They are stateless. They can be used to enforce customer access controls, and they can be generated from any location. A token can then be shared with a customer (via cookie, email link, or other means). With a token, customers can either access portions of SessionM APIs directly, or pass it to a server where it can be used on the customer’s behalf.

For example, you could use this API to obtain an authorization token and embed it as a parameter in an email link. Doing so allows a thin, API-driven web site to use the token to authenticate the customer and power an online store for spending points.

If you prefer an alternative means for granting customers login access, you might consider the approach offered by the Access Tokens API. The access tokens managed by this API can be revoked at any time, despite whatever time may be optionally specified for the token's TTL. When called, the delete routes servicing these tokens invalidate a token's related session cookie.

This API facilitates the creation and retrieval of authorization tokens. It provides the following methods:

Create a Request for a New Authorization Token

Specify a request to obtain a new authorization token, which could be embedded as a parameter in an email link. Doing so allows a thin, API-driven web site to use the token to authenticate the customer and power an online store for spending points.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/tokens
POST /priv/v1/apps/:api_key/external/users/:external_id/tokens

Endpoints Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it can pass in a request object that contains the ttl attribute. This optional integer specifies time in seconds until the requested authorization token expires. The default is one day with a maximum lifetime of ten days.

Consider the following sample:

▿ JSON Request

{
  "ttl":172800
}

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object. This object contains the auth_token key-value pair, which is the requested token.

Consider the following sample:

▿ JSON Response

{
  "status":"ok",
  "user":
  {
    "auth_token":"xxxx-yyyy-zzzz"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid token The specified token was invalid.
user not found Unable to find the specified customer.
permission denied Access denied for creating tokens.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Validate an Authorization Token

Retrieves a validation for an authorization token. Token validation is a useful way for a server to ensure that a customer has been granted access and that the grant is still active. Once a token has been presented to a server, that server can validate the token via a backend API call to SessionM’s servers.

In keeping with the example of a customer accessing an online store via an email link that contains an authorization token, this method can be used by the rewards store to validate the incoming customer. If the online store wants to drop its own session cookie for the transaction, it could use its own token's expires_on attribute to ensure that it expires before the customer's. Or, alternatively, the method could be used by the store to make a backend call to refresh the authorization token.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/tokens/validate?auth_token=xxxx-yyyy-zzzz

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a token object.

Consider the following sample:

▿ JSON Response

{
  "status":"ok",
  "token":{
    "user_id":"xxxx",
    "expires_on":"2015-02-01 04:00"
  }
}


This object is detailed in the following table:

Response Attributes for Token

Attribute Type Description
user_id string SessionM ID for the customer requesting the authorization token.
expires_on string Datetime on which the authorization token expires.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Returned String Reason
invalid api key The specified API key was invalid.
invalid token The specified token was invalid.
missing token No token was specified as a part of the request.
user not found Unable to find the specified customer.
unknown api_key Request specified an unknown API key.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Authorization Token and a Standard Profile

Retrieves an authorization token and a standard profile in one operation. Standard profile data can be utilized for personalization. To extend the example of a customer accessing an online store via an email link that contains an authorization token, this method can be used by the organization to customize the email containing the link. Instead of some generic salutation, it could include the customer's name. For example, "Dear Joe, here's your online shopping link..."

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id?user[auth_token]=true
GET /priv/v1/apps/:api_key/external/users/:external_id?user[auth_token]=true

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform. Returns standard profile for internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform. Returns standard profile for external customer.
user[auth_token] Retrieves authentication token for customer when set to true. For example: user[auth_token]=true.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "account_status": "good",
        "auth_token": "v2--5W8kaVGHoUpxcm98nrmtp287KVHZChE9hXWaagYeXJw=--hUvxfLBwMdTBUCwiYLSi7YNv6gMOYQYsOZJyxM1OjemkAR0K9dqRj6f-hvei1K8MNA==",
        "created_at": "2016-10-21 18:12:22",
        "dob": "1980-01-01",
        "email": "john.smith@fake.email.addr",
        "external_id": "654321",
        "gender": "m",
        "id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
        "proxy_ids": [],
        "registered_at": "2016-10-21 18:12:22",
        "suspended": false,
        "updated_at": "2016-10-21 18:12:22"
    }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve an Authorization Token and a Custom Profile

Retrieves an authorization token and a custom profile in one operation. Custom profile data can be utilized for personalization. To extend the example of a customer accessing an online store via an email link that contains an authorization token, this method can be used by the organization to customize the email containing the link. Instead of the link being presented in a generic message that could apply to anyone, it could be part of an email that includes unique details about the customer, such as their title and recent purchase information. For example, "Dear Dr. Jones, since you recently purchased a new gas grill, we suspect you might need a new cover to protect it from the elements. Follow this link to see what we have in stock..."

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true&user[auth_token]=true
GET /priv/v1/apps/:api_key/external/users/:external_id?user[user_profile]=true&user[auth_token]=true

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
user[user_profile] Retrieves profile for customer when set to true. For example: user[user_profile]=true.
user[auth_token] Retrieves authentication token for customer when set to true. For example: user[auth_token]=true.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object.

The user_profile attribute is not detailed in that section; it contains a set of custom profile attributes such as user_title, program_tier and locale.

All of these custom attributes extend the standard profile for the customer. Note that _version is a system-defined, default attribute.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "account_status": "good",
        "auth_token": "v2--5W8kaVGHoUpxcm98nrmtp287KVHZChE9hXWaagYeXJw=--hUvxfLBwMdTBUCwiYLSi7YNv6gMOYQYsOZJyxM1OjemkAR0K9dqRj6f-hvei1K8MNA==",
        "created_at": "2016-10-21 18:12:22",
        "dob": "1980-01-01",
        "email": "john.smith@fake.email.addr",
        "external_id": "654321",
        "gender": "m",
        "id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
        "proxy_ids": [],
        "registered_at": "2016-10-21 18:12:22",
        "suspended": false,
        "updated_at": "2016-10-21 18:12:22",
        "user_profile": {
          "_version": 1,
          "user_title":"mr",
          "program_tier":4,
          "locale":"fr-ca"
       }
    }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Access Tokens API

Access Tokens can be used to grant login access to customers as well as invalidate those logins. When revoking these OAuth access tokens, you can delete either a specific token or all tokens for the customer.

This API provides an alternative means for granting customers login access than the approach offered by the Authorization Tokens API. The access provided via authorization tokens terminates only when the associated "TTL" (Time to Live) expires. On the other hand, the access tokens managed by the Access Tokens API can be revoked at any time, despite whatever time may be optionally specified for the token's TTL. When called, the delete routes servicing these tokens invalidate a token's related session cookie.

This API facilitates the creation and deletion of access tokens. It provides the following methods:

Create an Access Token

Specify a request to create a new access token.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/access_token
POST /priv/v1/apps/:api_key/external/users/:external_id/access_token

Endpoints Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it can pass in an optional request object that contains two attributes, as shown below:

▿ JSON Request

{
    "token": "token_string",
    "expires_in": 3600
}


These attributes are detailed in the following table:

Request Attributes for Access Token

Attribute Type
Required/Optional
Description
token string
optional
Unique identifier for the token.
expires_in integer
optional
Time to live (TTL) in seconds until the requested access token expires.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an access_token object.

Consider the following sample:

▿ JSON Response

{
    "access_token": {
        "access_token": "access_token",
        "created_at": 1518627262,
        "expires_in": 1209600,
        "refresh_token": "663792192674a527709a4e5d3ed1a9c0442d502bc2526633"
    },
    "status": "ok"
}


This object is detailed in the following table:

Response Attributes for Access Token

Attribute Type Description
access_token string Unique identifier for the token.
created_at integer Unix timestamp of when the access token was created.
expires_in integer Time to live (TTL) in seconds until the access token expires.
refresh_token string OAuth refresh token.
revoked_at string Specifies the date and time the access token was revoked (deleted). Attribute appears only in the response object generated by the access token delete method.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Revoke an Access Token

Revoke, or delete, an existing access token.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/access_token
DELETE /priv/v1/apps/:api_key/access_token?auth_token=xxxx
DELETE /priv/v1/apps/:api_key/access_token?access_token=xxxx
DELETE /priv/v1/apps/:api_key/access_token?token=xxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
auth_token Authorization token to delete.
access_token Access token to delete.
token Token to delete.

Request Object

When this method runs, it can pass in a required request object that contains one attribute, token_to_revoke, which is a string that identifies the access token to revoke and is shown below:

▿ JSON Request

{
    "token": "token_to_revoke"
}

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an access_token object.

Consider the following sample:

▿ JSON Response

{
    "access_token": {
        "access_token": "access_token",
        "revoked_at": "2018-02-14T16:55:15Z"
    },
    "status": "ok"
}


For more information on this response and its attributes, see the Response Attributes for Access Token table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Revoke All Access Tokens

Revoke, or delete, all access tokens associated with a specific customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/users/:user_id/access_token
DELETE /priv/v1/apps/:api_key/external/users/:external_id/access_token

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

The response object returned by this method contains only a status value-pair for the transaction. Consider the following sample:

▿ JSON Response

{
    "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Customer Profile APIs

The SessionM Platform represents customer data with profile objects. A profile is a template for creating customers in the system. Each instance of a profile expresses data defined for a specific customer.

Customer profile services provide a variety of methods for managing both standard and custom profiles for customers. Standard profiles contain basic demographic data about the customer that is pre-configured in the platform. For example, the customer's name and gender. Custom profiles, however, contain custom attributes that reflect the unique characteristics of an organization's customers. Often these attributes express information that can be leveraged for promotional campaign targeting. For example, while an adult customer's date of birth (dob) is a standard profile attribute that can be used to sell merchandise to the customer, it isn't very useful to a promotion targeting children. Such a campaign would benefit instead by a custom profile attribute that captures the birthday of the customer's child (son_dob or daughter_dob).

Note: In most cases, these APIs are not intended for integrations with point-of-sale systems. For specific point-of-sale APIs that are designed for the management of customer profiles, please see the SessionM POS API documentation.

Standard Profile API

This API features User objects, which are the primary mechanism for working with standard profiles for customers. These objects contain fairly basic or obvious customer characteristics such as name, email address and date of birth. Note that this standard data can also include state characteristics about the customer, such as whether or not the customer is active.

This API provides a set of methods that do the following:

Create a Standard Profile

Builds a new standard profile for a customer. Provides the primary operation for adding a standard profile to the platform and specifying that customer's characteristics.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains a user object, as shown below:

▿ JSON Request

{
  "user":
  {
     "external_id":"1284111",
     "opted_in":"true",
     "external_id_type": "facebook",
     "email":"john.smith@test.com",
     "first_name":"John",
     "last_name":"Smith",
     "gender":"m",
     "dob":"1980-01-01",
     "address":"7 Tremont Street",
     "city":"Boston",
     "state":"MA",
     "zip":"02021",
     "country":"USA",

     "referral" :
     {
        "referral_code" : "JOHN-70A756",
        "source" : "John"
     },  
     "phone_numbers":
     [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"]
     }]
   }
}


The object's attributes are detailed in the following table:

Request Attributes for User

Attribute Type
Required/Optional
Description
external_id string or integer
required, if email is not specified.
Identifier for customer in external system.
opted_in boolean
optional
Indicates whether customer is opted in to a loyalty program. Defaults to "true" if no attribute value is specified. Set to "false" to opt out a customer.
external_id_type string
optional
Type associated with external identifier.
email string
required, if external_id is not specified.
Customer's email account. Data is encrypted for storage on the disk.
locale string
optional
Customer-preferred locale. Format is [language designator]-[region designator] where language designator is ISO-639-1 and region designator is ISO-3166-1. For example en-us.
ip string
optional
Customer's IP address used during registration.
dob string
optional
Customer's date of birth. Format is YYYY-MM-DD.
address string
optional
Customer's address.
city string
optional
Customer's city of residence.
state string
optional
State/province/region of customer's residence. If IP address is provided, state, province or region can be derived from it.
zip string
optional
Zip or postal code of customer's residence. If IP address is provided, zip code can be derived from it.
country string
optional
Customer's country of residence. For example, USA, CAN). Compliant with ISO-3166-1 and Alpha-3 standards. If IP address is provided, country can be derived from it. Country must be specified as a 3-digit code; for example, USA.
gender string
optional
Gender of customer. Passed in as m or f.
first_name string
optional
Customer's first name.
last_name string
optional
Customer's last name (surname).
referral object
optional
Referral code associated with a customer participating in a refer-a-friend program. Codes can be either specified in the request object or generated upon customer creation. Specified referral codes are utilized by "referees," customers that stipulate another person's code as they register or create their own user account. Alternatively, generated referral codes are utilized by "referrers," customers who send their codes via social media to other customers using them in their own registration process. Note that the enable_referrals flag in the Resources.rewards_system file must be set to true in order to utilize this referral logic. For more information, see the Request Attributes for Referral table.
phone_numbers array
optional
Phone numbers associated with customer. Customers can have one or multiple numbers. For more information, see the Request Attributes for Phone Numbers table.

Request Attributes for Referral

Attribute Type
Required/Optional
Description
referral_code string
optional
Referral code defined for customer.
source string
optional
Customer name associated with referral code.

Request Attributes for Phone Numbers

Attribute Type
Required/Optional
Description
phone_number string
required
Phone number associated with customer.
phone_type string
optional
Type of phone number associated with customer. Default values include: "mobile", "office", "home", "fax" and "other".
preference_flags array
optional
Array of flags that correspond to some setting. For example, "primary" indicates the phone number is the customer's primary number.
Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object.

Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "user":
  {
    "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
    "external_id":"1284111",
    "proxy_ids": [],    
    "opted_in":"true",
    "email":"john.smith@test.com",
    "identifiers":
    [{
        "external_id":"1234abcd","external_id_type":"facebook"
    }],
    "first_name":"John",
    "last_name":"Smith",
    "gender":"m",
    "dob":"1980-01-01",
    "account_status":"good",
    "auth_token": "v1--5W8kaVGHoUpxcm98nrmtp287KVHZChE9hXWaagYeXJw=--hUvxfLBwMdTBUCwiYLSi7YNv6gMOYQYsOZJyxM1OjemkAR0K9dqRj6f-hvei1K8MNA==",
    "created_at": "2016-10-21 18:12:22",
    "address":"7 Tremont Street",
    "city":"Boston",
    "state":"MA",
    "zip":"02021",
    "country":"USA",
    "available_points":120,
    "tier":"silver",
    "referrer_code": "JOHN-70A756",
    "registered_at": "2016-10-21 18:12:22",
    "suspended": false,
    "updated_at": "2016-10-21 18:12:22",
    "phone_numbers":
    [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"],
        "verified_ownership": false
    }]
  }
}


The following tables document this object, along with the associated account statuses:

Response Attributes for User

Attribute Type Description
id string Identifier for customer within platform.
external_id string Identifier for customer in external system.
proxy_ids array Special type of external IDs.
opted_in string Boolean that identifies if customer is opted in to a loyalty program.
email string Customer's email account. Data is encrypted for storage on the disk.
identifiers array Array of external ID identifiers. See the Response Attributes for Identifiers table.
first_name string Customer's first name.
last_name string Customer's last name (surname).
gender string Gender of customer. Passed in as m or f.
dob string Customer's date of birth. Format is YYYY-MM-DD.
account_status string Status of the customer's account. See the Response Attributes for Account Statuses table.
auth_token string Authorization token returned by this endpoint.
created_at datetime Datetime user account was created. Format is not configurable. Format is YYYY-MM-DD HH:MM:SS
address string Customer's address.
city string Customer's city of residence.
state string State/province/region of customer's residence. If IP address is provided, state, province or region can be derived from it.
zip string Zip or postal code of customer's residence. If IP address is provided, zip code can be derived from it.
country string Customer's country of residence. For example, USA, CAN). Compliant with ISO-3166-1 and Alpha-3 standards. If IP address is provided, country can be derived from it.
available_points integer Customer's current points balance. Displays when the enable_mpoints_info_in_users_api setting is enabled, which is accessed via the SessionM Admin Portal. For more information, consult your Customer Success contact.
tier string Loyalty program category achieved by customer.
referrer_code string Referral code that can be specified or generated for a newly created customer. Customers can either send or receive these codes as part of an active refer-a-friend program. Note that the enable_referrals flag in the Resources.rewards_system file must be set to true in order to utilize this referral logic. For more information, see the referral attribute which is documented in the Request Attributes for User table.
registered_at datetime Datetime user account was registered. Format is not configurable. Format is YYYY-MM-DD HH:MM:SS
suspended boolean Reflects whether or not customer service representative has suspended user account for Terms of Service (TOS) violation. Value of true indicates user was suspended; value of false indicates user NOT suspended (user is active).
updated_at datetime Datetime user account was updated. Format is not configurable. Format is YYYY-MM-DD HH:MM:SS
phone_numbers array Phone numbers associated with customer. Customers can have one or multiple numbers. For more information, see the Response Attributes for Phone Numbers table.

Response Attributes for Identifiers

Attribute Type Description
external_id string External identifier for customer.
external_id_type string Type for external identifier. For example, "Facebook".

Response Attributes for Account Statuses

Attribute Type Description
good string Account in good standing.
rev string Account was reviewed by administrator.
warn string Account was issued a warning.
multi string Account is blocked due to multiple accounts.
tos string Account is blocked due to TOS violations.
vol string Account is under customer-requested suspension.
reported string Account is reported by a customer for violation.
unverified string Waiting for customer to verify email.
not_a_member string Customer doesn't exist in our system.

Response Attributes for Phone Numbers

Attribute Type Description
phone_number string Phone number associated with customer.
phone_type string Type of phone number associated with customer. Default values include: "mobile", "office", "home", "fax" and "other".
preference_flags array Array of flags that correspond to some setting. For example, "primary" indicates the phone number is the customer's primary number.
verified_ownership boolean Specifies whether or not customer has number. Defaults to false.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
external_id_in_use The external ID used to create the customer's account is already in use.
email_already_in_use The email address used to create the customer's account is already in use.
an_email_or_external_id_is_required An email address or external ID is required to create the account.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Confirm a Standard Profile via Email

Confirms the creation of a standard profile by sending an email to the associated customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/emails/confirmation
POST /priv/v1/apps/:api_key/external/users/:external_id/emails/confirmation
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

Only status is returned for for a successful operation. Consider the following sample:

▿ JSON Response

{
  "status": "ok"
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
UserNotFound Email action not found.
NotAllowed User email confirmation is disabled.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a Standard Profile

Retrieves an existing standard profile for a customer with all of the profile's associated attributes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id
GET /priv/v1/apps/:api_key/external/users/:external_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
show_identifiers Optional boolean that displays a list of external identifiers and their corresponding types for customers. Syntax for parameter is show_identifiers=true.
Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object. Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "account_status": "good",
        "created_at": "2016-10-21 18:12:22",
        "dob": "1980-01-01",
        "email": "john.smith@fake.email.addr",
        "external_id": "654321",
        "opted_in": "true",
        "identifiers":
        [
          {"external_id":"1234abcd","external_id_type":"facebook"}
        ],
        "gender": "m",
        "id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
        "proxy_ids": [],
        "registered_at": "2016-10-21 18:12:22",
        "suspended": false,
        "updated_at": "2016-10-21 18:12:22",
        "referrer_code": "JOHN-70A756",
        "phone_numbers":
        [{
            "phone_number": "1234123123",
            "phone_type": "home",
            "preference_flags": ["primary"],
            "verified_ownership": false
        }]     
    }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_is_not_found Unable to find the customer for the specified user ID or external ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Multiple Standard Profiles

Retrieves multiple standard profiles for customers with all of their associated attributes

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_ids Required array of strings that are the UIDs of multiple customers.
show_identifiers Optional boolean that displays a list of external identifiers and their corresponding types for customers. Syntax for parameter is show_identifiers=true.
Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a users array. The array contains multiple user objects, which are detailed here. Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "users": [
    {
      "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
      "external_id":"1284111",
      "opted_in":"true",
      "email":"john.smith@test.com",
      "identifiers":
      [
        {"external_id":"1234abcd","external_id_type":"facebook"}
      ],
      "first_name":"John",
      "last_name":"Smith",
      "gender":"m",
      "dob":"1980-01-01",
      "account_status":"good",
      "address":"7 Tremont Street",
      "city":"Boston",
      "state":"MA",
      "zip":"02021",
      "country":"us",
      "referrer_code": "JOHN-80A756",
      "phone_numbers":
      [{
          "phone_number": "7895642324",
          "phone_type": "home",
          "preference_flags": ["primary"],
          "verified_ownership": false
      }]
    },
    {
      "id":"e861e994-8bc8-11e6-999a-42f789a66661",
      "external_id":"111",
      "email":"jane.doe@test.com",
      "first_name":"Jane",
      "last_name":"Doe",
      "gender":"f",
      "dob":"1982-07-01",
      "account_status":"good",
      "address":"7 Tremont Street",
      "city":"Boston",
      "state":"MA",
      "zip":"02021",
      "country":"us",
      "referrer_code": "JANE-70A756",
      "phone_numbers":
      [{
          "phone_number": "1234123123",
          "phone_type": "home",
          "preference_flags": ["primary"],
          "verified_ownership": false
      }]
    }
  ]
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Code Reason
no ids specified No user IDs were specified as a part of the request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Standard Profile

Updates a standard profile for a customer with new data.

Developers should bear in mind that these endpoints, which update a standard profile, can create the profile and update it in one operation. As such, it isn't necessary to call a create endpoint and then follow that call with another that performs an update. Since this capability can be enabled or disabled, contact your customer success representative if you need assistance.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/users/:user_id
PUT /priv/v1/apps/:api_key/external/users/:external_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Consider the following sample:

▿ JSON Request

{
  "user":
    {
    "first_name":"Jimmy",
    "external_id":"1284111",
    "external_id_type": "facebook"
    }
}


For information, see the user request object.

Response Object

Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "user":
    {
    "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
    "external_id":"1284111",
    "opted_in":"true",
    "email":"john.smith@test.com",
    "identifiers":
    [
      {"external_id":"1234abcd","external_id_type":"facebook"}
    ],
    "first_name":"Jimmy",
    "last_name":"Smith",
    "gender":"m",
    "dob":"1980-01-01",
    "account_status":"good",
    "address":"7 Tremont Street",    
    "city":"Boston",
    "state":"MA",
    "zip":"02021",
    "country":"USA",
    "phone_numbers":
    [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"],
        "verified_ownership": false
    }]
  }
}


For information, see the user response object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Returned String Reason
external id in use The external ID used to create the customer's account is already in use.
Email Already In Use The email address used to create the customer's account is already in use.
an email or external_id is required An email address or external ID is required to create the account.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Standard Profile

Deletes a standard profile for a customer from the system.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/users/:user_id
DELETE /priv/v1/apps/:api_key/external/users/:external_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "user":
    {
    "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
    "external_id":"1284111",
    "opted_in":"true",
    "email":"john.smith@test.com",
    "identifiers":
    [
      {"external_id":"1234abcd","external_id_type":"facebook"}
    ],
    "first_name":"John",
    "last_name":"Smith",
    "gender":"m",
    "dob":"1980-01-01",
    "account_status":"good",
    "address":"7 Tremont Street",    
    "city":"Boston",
    "state":"MA",
    "zip":"02021",
    "country":"USA",
    "referrer_code": "JOHN-70A756",
    "phone_numbers":
    [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"],
        "verified_ownership": false
    }]
  }
}


For information, see the user response object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Returned String Reason
user is not found Unable to find a customer for the specified customer ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Search for a Standard Profile

Searches for an existing standard customer profile. Returns the specified customer profile with all of its associated attributes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/search?email=test@example.com
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
email Customer's email address; required for search. For example: search?email=test@example.com
user[user_profile] Optional boolean that returns user_profile data.
show_identifiers Optional boolean that displays a list of external identifiers and their corresponding types for customers. Syntax for parameter is show_identifiers=true.
Request Object

Not applicable.

Response Object

Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "user":
    {
    "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
    "external_id":"1284111",
    "opted_in":"true",
    "email":"john.smith@test.com",
    "first_name":"Jimmy",
    "last_name":"Smith",
    "gender":"m",
    "dob":"1980-01-01",
    "account_status":"good",
    "address":"7 Tremont Street",    
    "city":"Boston",
    "state":"MA",
    "zip":"02021",
    "country":"USA",
    "referrer_code": "JOHN-70A756",
    "phone_numbers":
    [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"],
        "verified_ownership": false
    }]
  }
}


For information, see the user response object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
not found Unable to find a customer for the specified user ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Custom Profile API

Custom data is defined by the developer, who can programmatically define attributes, as well as their corresponding validation filters. These attributes will surface in the platform for audiences, targeting and personalization efforts.

Custom attributes can be direct response data or observed data derived from the customer's actions. What did the customer buy? What application did the customer open? Such actions can be represented by custom profile attributes.

This API features User Profile objects, which can be used to append the standard customer profile, extending it beyond the pre-configured attributes available upon the initial system installation.

This observed customer profile data broadly falls into the following categories:

This interface provides a set of methods that do the following:

Note: All of the APIs documented on this site contain sections that present a superset of the named attributes available to any request or response object. The Custom Profile API is the exception. Since these attributes are client-defined, every implementation's custom profile attributes are different. What is held in common across all custom profile attributes, however, are the data types that can be used to define the attributes. For example, filter arrays that format attribute values; or a numericality object that stipulates whether attribute values can be less or more than a specified amount. The section that follows presents all of the attribute data types available to create your own attributes. In addition, subsequent sections feature a set of request and response samples that utilize a variety of these attribute data characteristics.

Attribute Definition Characteristics

The SessionM Platform supports the design and definition of attributes that can extend the customer model an organization uses. The platform's default implementation of these attributes extends the custom profiles associated with customers. This model, users_profile, allows you to define custom attributes to capture data about a customer.

The building blocks of these attribute definitions are a set of validation rules and data types. The type dictates the validation logic for the platform to apply, as well as the desired format for return data. In addition, filters are used to normalize the data. This approach acts as a data integrity and protection mechanism.

The platform offers the following rules and attribute types to support the creation of custom profile attributes:

Attribute Types

All attributes require a type.

Attribute Type Description
boolean Attribute value can be true or false.
string Attribute value must be a string.
integer Attribute value must be an integer.
decimal Attribute value must be a decimal.
date Attribute value must be a date. Format is not configurable. Format is YYYY-MM-DD.
datetime Attribute value must be a datetime. Format is not configurable. Format is YYYY-MM-DD HH:MM:SS.
complex Attribute that contains attributes. Can include a list, which is a boolean specifying that the input comprises multiple strings or numerals. If true, inputs are multiple strings or numerals; if false, input is a single string or value.
Filter Rules

Filter rules are arrays and are optional to the definition of an attribute. They normalize request data input strings to ensure data integrity within the SessionM Platform.

Filter Rule Description
downcase Lower case the string.
upcase Upper case the string.
strip Remove leading and trailing white spaces in the string.
rstrip Remove trailing white space in the string.
lstrip Remove leading white space in the string.
Validation Rules for Strings

Validation rules for strings apply to only data being inserted or updated. They are specified as objects and are optional.

Validation Rule Description
inclusion Object that specifies an array of strings that the data must match.
exclusion Object that specifies an array of strings that the data must not match.
format A regular expression string to constrain values within a pattern.
length Object that validates the length of strings. These rules include:

- maximum; cannot be longer than the specified value.
- minimum; cannot be shorter than the specified value.
- is; must be this exact number of specified characters.
caseinsensitive Boolean that specifies whether value submitted to API is lower-cased before validation logic is applied. true lower-cases data; false does not.
list Boolean that specifies that the input comprises multiple strings. If true, multiple strings; if false, single string.
Validation Rules for Integers and Decimals

Validation rules for integers and decimals apply to only data being inserted or updated. They are specified as objects and are optional.

Validation Rule Description
inclusion Object that specifies an array of numbers that the data must match.
exclusion Object that specifies an array of numbers that the data must not match.
numericality Object that validates integers and decimals. These rules include:

- greater_than; must be greater than the specified value.
- greater_than_or_equal_to; must be greater than or equal to the specified value.
- less_than; must be less than the specified value.
- less_than_or_equal_to; must be less than or equal to the specified value.
- even or odd; boolean that specifies that the number must be even or odd. when specified, either value must be set to true. note that both boolean values cannot be set simultaneously to true.
- integer_only; boolean that specifies that the number must be an integer. true indicates an integer.
- list; boolean that specifies that the input comprises multiple numerals. If true, multiple values; if false, single value.
Validation Rules for Dates and Datetimes

Validation rules for dates and datetimes apply to only data being inserted or updated. They are specified as objects and are optional. Date and datetime formats are not configurable.

Validation Rule Description
format A regular expression string to constrain values within a date or datetime pattern. For dates, format is YYYY-MM-DD; for datetimes, format is YYYY-MM-DD HH:MM:SS.
list Boolean that specifies that the date or datetime input comprises multiple strings. If true, multiple strings; if false, single string.

Create a Custom Profile

With this method, you can build a customer's entire custom profile. If the customer already has a custom profile, an error is returned.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST        /priv/v1/apps/:api_key/users/:user_id/models/user_profile
POST        /priv/v1/apps/:api_key/external/users/:external_id/models/user_profile
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

When this method runs, it passes in a user_profile request object, which contains whatever custom attributes you choose to create. Consider the following sample:

▿ JSON Request

{
   "user_profile": {
        "user_tier": "mrs",
        "program_tier": 2,
        "locale": "en-us"
    }
}


In this example of a request to create a custom profile, the request object contains a few attributes, user_tier, program_tier and locale. While each of these custom attributes is client-defined, the data types that define them are not. For more information on the rules governing attribute definition, see Attribute Definition Characteristics.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a user_profile object, shown below:

▿ JSON Response

{
   "status": "ok",
   "user_profile": {
        "_version": 1,
        "user_tier": "mrs",
        "program_tier": 2,
        "locale": "en-us"
    }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a response to the creation of a custom profile, the response object contains the following client-defined attributes: _version, user_tier, program_tier and locale. Note that _version is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
already_exists Customer profile already exists.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create an Attribute in a Custom Profile

Using this method, you can allow systems to add attributes to custom profiles within the platform. The type dictates the validation logic for the platform to apply, as well as the desired format for return data.

This approach acts as a data integrity and protection mechanism. Filters are used to normalize the data. For more information on the rules that govern data integrity, see Attribute Definition Characteristics.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/models/user_profiles/attributes
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in an attributes request object, which contains whatever custom attributes you choose to create, as shown below:

▿ JSON Request

{
  "attributes":{
    "user_title":{
      "type":"string",
      "filters":[
        "downcase",
        "upcase",
        "strip",
        "rstrip",
        "lstrip"
      ],
      "caseinsensitive":true,
      "inclusion":[
        "mr",
        "ms",
        "mrs",
        "dr"
      ],
      "exclusion":[
        "md"
      ],
      "length":{
        "minimum":2,
        "maximum":8
      }
    },
    "num_purchases":{
      "type":"integer",
      "inclusion":[
        3,
        4
      ],
      "exclusion":[
        2,
        5
      ],
      "numericality":{
        "greater_than_or_equal_to":4,
        "less_than":100,
        "even":true
      }
    }
  }
}


In this example of a request to create a custom profile attribute, the request object contains two "child" objects called user_title and num_purchases. While each of these custom attributes is client-defined, the data types that define them are not. For more information on the rules governing attribute definition, see Attribute Definition Characteristics.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a model object, as shown below:

▿ JSON Response

{
   "model":{
      "name":"user_profiles",
      "version":"8c510502-0aac-11e5-8563-788508912e2c",
      "request_key":"user_profile",
      "attributes":{
         "user_title":{
            "type":"string",
            "filters":[
               "downcase",
               "upcase",
               "strip",
               "rstrip",
               "lstrip"
            ],
            "caseinsensitive":true,
            "inclusion":[
               "mr",
               "ms",
               "mrs",
               "dr"
            ],
            "exclusion":[
               "md"
            ],
            "length":{
               "minimum":2,
               "maximum":8
            }
         },
         "num_purchases":{
            "type":"integer",
            "inclusion":[
               3,
               4
            ],
            "exclusion":[
               2,
               5
            ],
            "numericality":{
              "greater_than_or_equal_to":4,
              "less_than":100,
              "even":true
            }
         },
         "total_purchase_amount":{
            "type":"decimal",
            "greater_than_or_equal_to":0
         }
      }
   }
}


The following table documents this object:

Response Attributes for Model

Attribute Type Description
name string Name of the attribute model.
version string Version of the attribute model.
request_key string Identifier for the associated request object.
attributes object For information on attributes and how they are defined, see Attribute Definition Characteristics.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Error Type Returned String
exclusion options should contain only numeric values
exclusion options should contain only string values
exclusion should be an array
inclusion options should contain only numeric values
inclusion options should contain only string values
inclusion should be an array
length option cannot be used with maximum or minimum
length option should be an integer
length option maximum or minimum cannot be used with is
length option maximum should be an integer
length option minimum should be an integer
length options should be an integer for minimum, maximum, or is
length Valid keys are minimum, maximum, or is
name must match complex model name
numericality can not set odd and even
numericality can be true or the options only_integer, greater_than_or_equal_to, greater_than, less_than_or_equal_to, less_than
numericality option even must be set to true
numericality option odd must be set to true
numericality option only_integer must be set to true
numericality options greater_than_or_equal_to, greater_than, less_than_or_equal_to, less_than must be numeric
format must be a valid regex
format only used with strings
filters invalid filter specified valid filters are downcase, upcase, strip, rstrip, lstrip
not applicable not found
not applicable permission denied

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a Combined Standard and Custom Profile

Retrieves a customer profile that combines both standard and custom attributes when the endpoint includes the following:

user[user_profile]=true

Returns data about the customer along with details in the profile.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
user[user_profile] Returns custom profile in response when set to true. For example: user[user_profile]=true.
show_identifiers Optional boolean that displays a list of external identifiers and their corresponding types for customers. Syntax for parameter is show_identifiers=true.
Request Object

Not applicable

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object. In addition, the user object contains the attributes for the custom profile in a user_profile child object. Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "account_status": "good",
        "created_at": "2016-10-21 18:12:22",
        "dob": "1980-01-01",
        "email": "john.smith@fake.email.addr",
        "external_id": "654321",
        "identifiers":
        [
          {"external_id":"1234abcd","external_id_type":"facebook"}
        ],
        "gender": "m",
        "id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
        "proxy_ids": [],
        "registered_at": "2016-10-21 18:12:22",
        "suspended": false,
        "updated_at": "2016-10-21 18:12:22",
        "referrer_code": "JOHN-70A756",
        "user_profile": {
            "_version": 1,
            "user_title":"mr",
            "program_tier":4,
            "locale":"fr-ca"
        }
    }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a response to the retrieval of a custom profile, the response object contains the following client-defined attributes: user_title, program_tier and locale. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

Status and errors associated with retrieving a custom profile are the same as those for retrieving a standard profile. For more information, see Retrieve a Standard Profile.

Retrieve a Custom Profile

Retrieves a custom profile that contains only custom attributes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET     /priv/v1/apps/:api_key/users/:user_id/models/user_profile
GET     /priv/v1/apps/:api_key/external/users/:external_id/models/user_profile
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Not applicable

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user_profile object, as shown below:

▿ JSON Response

{
    "status": "ok",
    "user_profile": {
        "_version": 1,
        "user_title": "mr",
        "program_tier": 4,
        "locale": "fr-ca"
    }
}


Note that this object contains whatever custom attributes that you chose to create. In this example of a response to the retrieval of a custom profile, the response object contains the following client-defined attributes: user_title, program_tier and locale. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

Status and errors associated with retrieving a custom profile are the same as those for retrieving a standard profile. For more information, see that method's statuses and errors.

Update a Combined Standard and Custom Profile

Updates a customer profile with new standard and custom attributes. This method returns any unchanged existing standard data along with any changed data for both standard and custom attributes.

Developers should bear in mind that these endpoints, which update a combined standard and custom profile, can create the profile and update it in one operation. As such, it isn't necessary to call a create endpoint and then follow that call with another that performs an update. Since this capability can be enabled or disabled, contact your customer success representative if you need assistance.

Note: Unchanged data for any custom attribute must be re-specified in the update. If the request object for the update omits these existing custom attributes, their data is deleted. This is not the case for existing standard attributes. They are unaffected and remain unchanged if an update omits them. If an attribute is deleted, the previously submitted data is untouched. In this case, the Standard Profile API will no longer return it.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/users/:user_id
PUT /priv/v1/apps/:api_key/external/users/:external_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

When this method runs, it passes in a user request object, which contains a user_profile object, as shown below:

▿ JSON Request

{
  "user":{
    "user_profile":{
      "user_title":"mr",
      "program_tier":4,
      "locale":"fr-ca"
    }
  }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a request to update a custom profile, the request object contains the following client-defined attributes: user_title, program_tier and locale. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object. In addition, the user object contains the attributes for the custom profile in a user_profile child object. Consider the following example:

▿ JSON Response

{
  "status":"ok",
  "user":{
    "id":"6a89beac-a0dd-11e4-93f6-ddb808912e2c",
    "email":"john.smith@test.com",
    "user_profile":{
      "_version":4,
      "user_title":"Mr",
      "program_tier ":4,
      "locale":"fr-ca"
    }
  }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a response to the retrieval of a combined standard and custom profile, the response object contains the following client-defined attributes: user_title, program_tier and locale. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found No customer found for update request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Custom Profile

Updates a custom profile with new data for its custom attributes. This method returns an object that contains only custom attributes; all custom data is returned, both changed and unchanged.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/users/:user_id/models/user_profile
PUT /priv/v1/apps/:api_key/external/users/:external_id/models/user_profile
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

When this method runs, it passes in a request object that contains a user_profile object, as shown below:

▿ JSON Request

{
    "user_profile":{
        "user_title": "dr"
    }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a request to update a custom profile, the request object contains the client-defined attributes, user_title. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user_profile child object, as shown below:

▿ JSON Response

{
    "status": "ok",
    "user_profile": {
        "_version": 2,
        "user_title": "dr",
        "program_tier":4,
        "locale":"fr-ca"
    }
}


Note that the user_profile object contains whatever custom attributes that you chose to create. In this example of a response to the retrieval of a combined standard and custom profile, the response object contains the following client-defined attribute: user_title, program_tier and locale. The attribute _version is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found No customer found for update request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Custom Profile

Using this method, you can delete a customer's entire custom profile. Note that the customer and their standard profile remain intact.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE  /priv/v1/apps/:api_key/users/:user_id/models/user_profile
DELETE  /priv/v1/apps/:api_key/external/users/:external_id/models/user_profile
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an empty user_profile object, as shown below:

▿ JSON Response

{
    "status": "ok",
    "user_profile": {}
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found No customer found for delete request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete an Attribute in a Custom Profile

Using this method, you can remove attributes from a custom profile. Note that this method deletes the attribute from the profile, not just the attribute's value.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/models/user_profiles/attributes
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in an attributes request object, which contains whatever custom attributes that you choose to create. In this example of a request to delete a custom profile attribute, the request object contains two "child" objects called user_title and num_purchases. While each of these custom attributes is client-defined, the data types and rules that define them are not. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Consider the following sample:

▿ JSON Request

{
  "attributes":{
    "user_title":{
      "delete":true
    },
    "num_purchases":{
      "delete":true
    }
  }
}
Response Object

This response object is identical to the one returned for the method that retrieves all current model attributes. Consider the following sample:

▿ JSON Response

{
  "model":{
    "name":"user_profiles",
    "version":"8c510502-0aac-11e5-8563-788508912e2c",
    "request_key":"user_profile",
    "attributes":{
      "total_purchase_amount":{
        "type":"decimal",
        "greater_than_or_equal_to":0
      }
    }
  }
}


Click for more information.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found No customer found for delete request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Patch an Attribute in a Custom Profile

The SessionM Platform supports JSON Patch which provides a series of operations that can be applied to a JSON document. HTTP Patch extends the Hypertext Transfer Protocol (HTTP) with a method that performs partial modifications to resources. This implementation of HTTP Patch can apply partial changes to attributes residing in a customer's custom profile.

Evaluation of a JSON Patch document begins against a target JSON document. Operations are applied sequentially in the order they appear in the array. Each operation in the sequence is applied to the target document; the resulting document becomes the target of the next operation. Evaluation continues until all operations are successfully applied or until an error condition is encountered.

When patch operations are unsuccessful, the evaluation of the JSON Patch document should terminate and the application of the entire patch document fails.

For a fuller understanding of the HTTP Patch method, see the Internet Standards Track document that defines it.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PATCH   /priv/v1/apps/:api_key/users/:user_id/models/user_profile
PATCH   /priv/v1/apps/:api_key/external/users/:external_id/models/user_profile
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Objects

HTTP Patch endpoints can take the following types of request objects, each of which is best understood by its operation:

▿ JSON Request (Test)

{ "op": "test", "path": "/user_title", "value": "mrs" }
Request Object for Test

When the patch method runs, it can pass in an object that contains the following attributes:

Request Attributes for Test

Attribute Type
Required/Optional
Description
test string
required
Confirms that a value at target location is equal to the specified value. Value being compared in test operation must exist. Operation is successful if target location is equal to the value for the operation. For more information on the rules pertaining to being equal, see the section that discusses the test operation section in the Internet Standards Track document.
path string
required
Specifies location for desired data operation.
value string/integer
required
Specifies value to use for test operation.
Request Object for Remove

When the patch method runs, it can pass in an object such as the following:

▿ JSON Request (Remove)

{ "op": "remove", "path": "/keywords/1" }


This object contains the following attributes:

Request Attributes for Remove

Attribute Type
Required/Optional
Description
remove string
required
Removes the value at the target location. Target location must exist.
path string
required
Specifies location for desired data operation.
Request Object for Add

When the patch method runs, it can pass in an object such as the following:

▿ JSON Request (Add)

{ "op": "add", "path": "/keywords/-", "value": "comedy" }


This object contains the following attributes:

Request Attributes for Add

Attribute Type
Required/Optional
Description
add string Inserts new value into array or adds a new member to an object. Can replace value if member already exists.
path string
required
Specifies location for desired data operation.
value string/integer
required
Specifies value to use for add operation.
Request Object for Replace

When the patch method runs, it can pass in an object such as the following:

▿ JSON Request (Replace)

{ "op": "replace", "path": "/user_title", "value": "dr" }


This object contains the following attributes:

Request Attributes for Replace

Attribute Type
Required/Optional
Description
replace string Replaces value at the target location with the new specified value. Target location must exist.
path string
required
Specifies location for desired data operation.
value string/integer
required
Specifies value to use for replace operation.
Request Object for Move

When the patch method runs, it can pass in an object such as the following:

▿ JSON Request (Move)

{ "op": "move", "from": "/keywords/0", "path": "/preferences/-" }


This object contains the following attributes:

Request Attributes for Move

Attribute Type
Required/Optional
Description
move string Removes value at specified location and adds it to the target location.
from string Used for operations that require the relocation or duplication of data. Specifies location from which value is to be moved. "From" location cannot be moved into one of its children.
path string
required
Specifies location for desired data operation.
Request Object for Copy

When the patch method runs, it can pass in an object such as the following:

▿ JSON Request (Copy)

{ "op": "copy", "from": "/keywords/-", "path": "/preferences/0" }


This object contains the following attributes:

Request Attributes for Copy

Attribute Type
Required/Optional
Description
copy string Copies value at specified location to target location.
from string Used for operations that require the relocation or duplication of data. Specifies location from which value is to be copied. "From" location cannot be copied into one of its children.
path string
required
Specifies location for desired data operation.
Response Objects

In addition to a status key-value pair, the response objects returned by the endpoint that patch attributes contain a user_profile object that reflects its associated operation. The sections below document a response object for each kind of patch operation.

Response Object for Test

The response object for the test operation shows whether or not the attribute data specified in the request matches the existing data for the attribute, as follows:

▿ JSON Response (Test)

{
    "status": "ok",
    "user_profile": {
        "_version": 8,
        "keywords": [
            "comedy",
            "sci-fi"
        ],
        "preferences": [
            "comedy"
        ],
        "user_title": "dr"
    }
}


If the values match, the operation is successful. For example, the response shown above is a successful match to this request:

▿ JSON Request (Test)

[{"op":"test", "path":"/user_title", "value":"dr"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the following client-defined attributes: keywords, preferences and user_title. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object for Remove

The response object for the remove operation removes the value at the target location, as shown below:

▿ JSON Response (Remove)

{
    "status": "ok",
    "user_profile": {
        "_version": 7,
        "keywords": [
            "comedy",
            "sci-fi"
        ],
        "preferences": [
            "comedy"
        ],
        "user_title": "dr"
    }
}


The response shown above corresponds to this request:

▿ JSON Request (Remove)

[{"op":"remove", "path":"/keywords/1"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the following client-defined attributes: keywords, preferences and user_title. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object for Add

The response object for the add operation adds the value at the target location, as follows:

▿ JSON Response (Add)

{
    "status": "ok",
    "user_profile": {
        "_version": 1,
        "keywords": [
            "comedy"
        ]
    }
}


The response shown above corresponds to this request:

▿ JSON Request (Add)

[{"op":"add", "path":"/keywords/-", "value":"comedy"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the following client-defined attributes: keywords, preferences and user_title. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object for Replace

The response object for the add replace operation replaces the value at the target location with a new specified value, as follows:

▿ JSON Response (Replace)

{
    "status": "ok",
    "user_profile": {
        "_version": 4,
        "keywords": [
            "comedy"
        ],
        "preferences": [
            "comedy"
        ],
        "user_title": "dr"
    }
}


The response shown above corresponds to this request:

▿ JSON Request (Replace)

[{"op":"replace", "path":"/user_title", "value":"dr"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the following client-defined attributes: keywords, preferences and user_title. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object for Move

The response object for the move operation removes the value at the specified location and adds it to the target location, as follows:

▿ JSON Response (Move)

{
    "status": "ok",
    "user_profile": {
        "_version": 2,
        "preferences": [
            "comedy"
        ]
    }
}


The response shown above corresponds to this request:

▿ JSON Request (Replace)

[{"op":"move", "from":"/keywords/0", "path":"/preferences/-"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the preferences attribute. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Response Object for Copy

The response object for the copy operation copies the value at the specified location to the target location, as follows:

▿ JSON Response (Copy)

{
    "status": "ok",
    "user_profile": {
        "_version": 3,
        "keywords": [
            "comedy"
        ],
        "preferences": [
            "comedy"
        ]
    }
}


The response shown above corresponds to this request:

▿ JSON Request (Copy)

[{"op":"copy", "from":"/preferences", "path":"/keywords"}]


Note that the user_profile object in this response contains whatever custom attributes you chose to create. In this example, the response object contains the keywords and preferences attributes. One attribute, _version, is a system-defined, default attribute. For information on attributes and how they are defined, see Attribute Definition Characteristics.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid_format Failed patch request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Customer Affiliation API

This API builds and manages hierarchies, or affiliation trees, of customers represented in the platform as "nodes."

There are two types of nodes that can appear in a user affiliation tree - “collection” and “user.” A collection node is represented externally only as an object containing customers and/or other collection nodes - not represented as customers themselves. User nodes, on the other hand, are synonymous with current players/customers, but they can reside in an affiliation with either a collection node or a parent user node.

This API provides a set of methods that do the following:

Create an Affiliation

Builds a new affiliation tree.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/affiliations

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

When this method runs, it passes in a request object that contains a user_affiliation object, as shown below:

▿ JSON Request

{
    "user_affiliation": {
        "name": "ACME",
        "slug": "acme_inc”
    }
}


The object's attributes are detailed in the following table:

Request Attributes for User Affiliation

Attribute Type
Required/Optional
Description
name string
required
Name of the affiliation.
slug string
required
Primary identifier for the user, or customer, affiliation. Format: Any alphanumeric character combined with underscores and dashes.

Response Object

The response object returned by the method contains a user_affiliation object.

Consider the following sample:

▿ JSON Response

{
    "user_affiliation": {
        "name": "ACME",
        "slug": "acme_inc”
    }
}


This response object contains attributes documented in the Response Attributes for User Affiliation table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to create an affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Affiliations

Returns all affiliations for an organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/affiliations

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

Not applicable.

Response Object

The response object returned by the method contains a user_affiliation object.

Consider the following sample:

▿ JSON Response

{
    "user_affiliation": {
        "id": 1,
        "name": "ACME",
        "slug": "acme_inc”
    }
}


The following table documents this object:

Response Attributes for User Affiliation

Attribute Type Description
id string Unique user ID for a customer affiliation.
name string Name of the customer affiliation.
slug string Primary identifier for the customer affiliation. Format: Any alphanumeric character combined with underscores and dashes.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Affiliation

Returns a specific affiliation by an ID or a slug.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with the slug, which is the primary identifier for the user, or customer, affiliation. (Format: All caps and underscores instead of spaces.) Can also be specified with the unique user ID for the customer affiliation.

Request Object

Not applicable.

Response Object

The response object returned by the method contains a user_affiliation object.

Consider the following sample:

▿ JSON Response

{
    "user_affiliation": {
        "id": 1,
        "name": "ACME",
        "slug": "acme_inc”
    }
}


This response object contains the same attributes as the response object detailed in the Response Attributes for User Affiliation table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Root Node

Creates a root node, which is the top-level parent in the affiliation tree.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

When this method runs, it passes in a request object that contains a node object, as shown below:

▿ JSON Request

{
    "node" : {
        "name": "Acme",
        "external_affiliation_type": "Company"
    }
}


The object's attributes are detailed in the Request Attributes for Node table.

Response Object

The response object returned by the method contains a node object.

Consider the following sample:

▿ JSON Response

{
    "affiliation_type": "collection",
    "external_affiliation_type": "Company",
    "id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3",
    "name": "ACME"
}


The object's attributes are detailed in the Response Attributes for Node table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
node_exist Occurs when trying to create a new node whose name or slug name was already used by an existing node. In effect, node already exists.
missing_data Occurs when trying to create a node without parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Add a Collection Child Node to a Parent Collection Node

Creates a parent-child relationship between two nodes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

When this method runs, it passes in a request object that contains a node object, as shown below:

▿ JSON Request

{
    "node": {
        "name": "ACME Sales Team",
        "external_affiliation_type": "Division",
        "parent_id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3"
    }
}


The object's attributes are detailed in the following table:

Request Attributes for Node

Attribute Type
Required/Optional
Description
name string
required
Name of the child node.
external_affiliation_type string
required
Name of the type of group/affiliation. For example, "Company" or "Division."
parent_id string
optional
Unique customer ID of the parent node. If not specified, the child collection is assigned to the root node.

Response Object

The response object returned by the method contains a node object.

Consider the following sample:

▿ JSON Response

{
    "affiliation_type": "collection",
    "external_affiliation_type": "Division",
    "id": "7a987422-8b5e-11e8-9c5f-16f360c05ac3",
    "name": "ACME Sales Team",
    "parent_id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3"
}


The following table documents this object:

Response Attributes for Node

Attribute Type Description
affiliation_type string Defines the type of child node - collection or customer. In this case, always a collection.
external_affiliation_type string Name of the type of group/affiliation. For example, "Company" or "Division."
id string Unique customer ID of the child node.
name string Name of the child node.
parent_id string Unique customer ID of the parent node. If not specified, the child collection is assigned to the root node.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
node_exist Occurs when trying to add a node to a parent and that relationship already exists. In effect, user is already in this collection.
parent_does_not_exist Occurs when trying to add a node without specifying the parent or by using the wrong parent ID.
argument_error Occurs when trying to add a node to another node that is not a collection. In effect, parent must be a collection.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Add a Customer to a Parent Collection Node

Adds an existing customer to a parent collection.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

When this method runs, it passes in a request object that contains a parent ID, as shown below:

▿ JSON Request

{
  "parent_id": "7a987422-8b5e-11e8-9c5f-16f360c05ac3"
}


The parent_id attribute is an optional string for a unique customer ID of the parent node. If not specified, the child collection is assigned to the root node.

Response Object

The response object contains a status value-pair.

Consider the following sample:

▿ JSON Response

{
    "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
node_exist Occurs when trying to add a node to a parent and that relationship already exists. In effect, user is already in this collection.
parent_does_not_exist Occurs when trying to add a node without specifying the parent or by using the wrong parent ID.
argument_error Occurs when trying to add a node to another node that is not a collection. In effect, parent must be a collection.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Child Customer from a Parent Node

Deletes the relationship between a child customer and its parent's collection.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/users/:user_id/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
user_id Internal identifier for the customer within the SessionM Platform.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

When this method runs, it passes in a request object that contains a parent ID, as shown below:

▿ JSON Request

{
  "parent_id": "7a987422-8b5e-11e8-9c5f-16f360c05ac3"
}


The parent_id attribute is an optional string for a unique customer ID of the parent node.

Response Object

The response object contains a status value-pair.

Consider the following sample:

▿ JSON Response

{
    "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
parent_does_not_exist Occurs when trying to remove a node from a collection without specifying the parent. In effect, parent does not exist.
user_does_not_belong_to_this_parent Occurs when a node does not have a relationship with the specified parent. In effect, user does not belong to this parent.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Affiliations for a Customer

Returns all affiliations for a customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/user_id?user[affiliations]=true

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
user[affiliations]=true When set to true, retrieves the customer and traces their relationships in the affiliations tree, returning all of the customer's parents.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "activated": false,
        "affiliations": [
            {
                "nodes": [
                    {
                        "affiliation_type": "collection",
                        "external_affiliation_type": "Division",
                        "id": "7a987422-8b5e-11e8-9c5f-16f360c05ac3",
                        "name": "ACME AMEA Sales Division",
                        "parent_id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3"
                    },
                    {
                        "affiliation_type": "collection",
                        "external_affiliation_type": "Root Division",
                        "id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3",
                        "name": "ACME Sales Team"
                    }
                ],
                "user_affiliation": {
                    "id": 1,
                    "name": "ACME",
                    "slug": "ACME"
                }
            }
        ],
        "available_points": 0,
        "id": "75af3d92-a216-11e7-8a5e-3b9f60c05ac3",
        "opted_in": true,
        "test_points": 0,
        "unclaimed_achievement_count": 0
    }
}


The following table documents this object:

Response Attributes for User (Customer)

Attribute Type Description
activated boolean Determines if customer is verified.
nodes array List of nodes.
user_affiliation object Customer affiliation object.
available_points integer A customer’s available points.
id string Unique user ID of the customer.
opted_in boolean Indicates whether a customer has opted into the rewards program.
test_points integer Amount of points used on a test customer.
unclaimed_achievement_count integer A count of the unclaimed achievements for a customer.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Ancestors of a Customer within an Affiliation

Returns a list of ancestors - parent or grandparent nodes - for a specific customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/affiliations/:affiliation_slug_or_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

Not applicable.

Response Object

The response object returned by the method contains a nodes array.

Consider the following sample:

▿ JSON Response

{
  "nodes": [
    {
        "affiliation_type": "collection",
        "external_affiliation_type": "Division",
        "id": "7a987422-8b5e-11e8-9c5f-16f360c05ac3",
        "name": "ACME Sales Division",
        "parent_id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3"
    },
    {
        "affiliation_type": "collection",
        "external_affiliation_type": "Root Division",
        "id": "729d9366-8b5d-11e8-822e-b5fb60c05ac3",
        "name": "ACME Sales Team"
    }
  ],
  "user_affiliation": {
    "id": 1,
    "name": "ACME",
    "slug": "ACME"
  }
}


The attributes of this response are detailed within the Response Attributes for Node table and the Response Attributes for User Affiliations table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Root Nodes

Returns all root nodes in an affiliation.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/affiliations/:affiliation_slug_or_id/root_nodes

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

Not applicable.

Response Object

The response object returned by the method contains a user_affiliation object and a nodes array.

Consider the following sample:

▿ JSON Response

{
  "user_affiliation": {
    "id": 13,
    "name": "ACME",
    "slug": "ACME"
  },
  "nodes": [
    {
      "id": "b4b2b67a-8b92-11e8-8167-244b89cb62b1",
      "name": "ACME",
      "external_affiliation_type": "organization",
      "affiliation_type": "collection"
    }
  ]
}


The attributes of this response are detailed within the Response Attributes for User Affiliations table and the Response Attributes for Node table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Children

Returns all child nodes in a parent node.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/affiliations/:affiliation_slug_or_id/:user_id/children

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
affiliation_slug_or_id Identifier for the affiliation. Can be specified with either the slug or the unique identifier of the affiliation. (Format: All caps and underscores instead of spaces.)

Request Object

Not applicable.

Response Object

In addition to a status key-value pair and a count integer indicating the number of children, the response object returned by the method contains a children array populated with multiple child nodes.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "count": 1,
    "children": [
        {
            "id": "c65c98be-8b92-11e8-892f-a00d89cb62b1",
            "name": "ACME Sales Division",
            "external_affiliation_type": "division",
            "affiliation_type": "collection",
            "parent_id": "b4b2b67a-8b92-11e8-8167-244b89cb62b1"
        }
    ]
}


The children array contains a single child node, the attributes for which are detailed within the Response Attributes for Node table.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
node_not_in_affiliation Occurs when using an ID that is not apart of the affiliation.
missing_data Occurs when trying to see a specific affiliation without the correct parameters.
affiliation_disabled Occurs when the user affiliation feature is not enabled for an organization.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Places API

The Places API manages geographic data about places using location objects. These objects allow a third-party system to retrieve a list of places in proximity to a location coordinate and submit a check-in request to a particular place. Note that all distances are specified in meters.

This API provides the following methods:

Retrieve a List of Places

Retrieve a list of places around a specified location coordinate. The list of places can be scoped to particular region by specifying a radius around the coordinate. Note that the endpoints that utilize only the api_key, with (or without) a user_id or an external_id, are available for registered customers (users); however, GET /api/v1/apps/:api_key/places?auth_token=xxxxx applies to unregistered, anonymous customers.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/places
GET /priv/v1/apps/:api_key/users/:user_id/places
GET /priv/v1/apps/:api_key/external/users/:external_id/places
GET /api/v1/apps/:api_key/places?auth_token=xxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a location request object, as follows:

▿ JSON Request

{
  "location": {
      "latitude": 42.3493505,
      "longitude": -71.0492305,
      "limit": 50,
      "radius": 50
    }
}


The request object can also contain a filter_by attribute, as shown below:

▿ JSON Request (Filter by Creative ID)

{
  "location": {
      "latitude": 42.3493505,
      "longitude": -71.0492305,
      "limit": 50,
      "radius": 50
    },
  "filter_by": 123
}


This attribute is an optional integer that uses the creative ID to filter, or narrow down, ad units, which are pieces of content that carry their own metadata. The argument specified is the UUID of the ad unit. When used, the attribute returns valid locations that are part of the specified ad unit.

The location object contains several attributes, which are detailed in the following table:

Request Attributes for Location

Attribute Type
Required/Optional
Description
latitude float
required
Latitude coordinate.
longitude float
required
Longitude coordinate.
limit integer
optional
Maximum number of venues to return.
radius integer
optional
Maximum radius of returned venues.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the places object, as follows:

▿ JSON Response

{
  "status": "ok",
  "places": [
    {
      "id": "0504d69e-899c-11e6-973f-2a7fc1d29f66",
      "name": "A Fast Food Store",
      "state": "checkable",
      "distance": 0,
      "distance_label": "You're Here!",
      "accepted_distance": 125,
      "promoted": false,
      "points": 10,
      "icon": "http://host/images/image.png",
      "location": {
        "lat": 41.235166,
        "lng": -88.94473,
        "address": "123, Main St",
        "city": "Boston",
        "state": "MA"
      },
      "check_in": {
        "place_id": "0504d69e-899c-11e6-973f-2a7fc1d29f66",
        "venue_id": 10288,
        "creative_id": null,
        "state": "checkable",
        "distance": 0
      }
    },
    {
      "id": "0504dab8-899c-11e6-958b-b4fec1d29f66",
      "name": "Convenience Store",
      "state": "toofar",
      "distance": 1402,
      "distance_label": "0.9 miles",
      "accepted_distance": 125,
      "promoted": false,
      "points": 10,
      "icon": "http://host/images/m-place.png",
      "location": {
        "lat": 42.847594,
        "lng": -88.947569,
        "address": "456 Second St",
        "city": "Boston",
        "state": "MA"
      },
      "check_in": {
        "place_id": "0504dab8-899c-11e6-958b-b4fec1d29f66",
        "venue_id": 21157,
        "creative_id": null,
        "state": "toofar",
        "distance": 1402
      }
    }
  ]
}

Places Object

The Places object contains several attributes, some of which are other "child" objects, such as location and check_in.

The following table provides details on the places object:

Response Attributes for Places

Attribute Type Description
id string UUID of place.
name float Name of the place.
state float Check-in state. Can include:

checkable - Can check in to the place now.
alreadycheckedin_checkable - Checked in once, but the place supports multiple checkins.
alreadycheckedin_toofar - Already checked in to the place, and it is too far from the current location.
blocked_checkable - Customer is blocked from checking in to the place but it is with in check in radius.
blocked_toofar - Customer is blocked from checking in to the place and it is outside check in radius.
blocked_limithit - Customer is blocked from checking in to the place because the customer reached check in limit.
toofar - Place is too far from the current location.
distance integer Distance from specified coordinate.
distance_label integer Distance label.
accepted_distance integer Accepted distance to be able to check-in.
promoted boolean Determines if place is promoted with an ad. Value of true for yes; false for no.
points integer Points customer receives for check-in; points can vary based on location.
icon string Icon for the place.
location object See table below.
check_in object See table below.
Location Object

The following table provides details on the places object:

Response Attributes for Location

Attribute Type Description
lat float Latitude of the location.
lng float Longitude of the location.
address string Street address of the location.
city string City of the location.
state string State/province/region of customer's residence.
Check_In Object

The following table provides details on the check_in object:

Response Attributes for Check-In

Attribute Type Description
place_id string ID associated with the check-in.
venue_id integer ID of the place.
creative_id integer Platform-generated ID of the ad unit content, or creative content.
state string Check-in state. Can include:

checkable - Can check in to the place now.
alreadycheckedin_checkable - Checked in once, but the place supports multiple checkins.
alreadycheckedin_toofar - Already checked in to the place, and it is too far from the current location.
blocked_checkable - Customer is blocked from checking in to the place but it is with in check in radius.
blocked_toofar - Customer is blocked from checking in to the place and it is outside check in radius.
blocked_limithit - Customer is blocked from checking in to the place because the customer reached check in limit.
toofar - Place is too far from the current location.
distance integer Distance away from being able to check-in.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
access_denied Loyalty setting for mPlaces not enabled in current tenant.
check_in_limit_reached Check-in limit reached by the customer for this application.
check_in_too_far_away Check in location is not in the check-in radius.
check_in_not_available Already checked in to this place or check-in attempt is blocked.
missing_data Query did not contain location or check-in data.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Check-in to a Place

This method allows the submittal of a check-in request for a particular place.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/places/:place_id/check_ins
POST /priv/v1/apps/:api_key/users/:user_id/places/:place_id/check_ins

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
place_id UUID of the check_in.
user_id Internal identifier for the customer within the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a check_in object, as shown below:

▿ JSON Request

{
  "check_in": {
    "place_id": "f3812fae-ebb1-11e5-953d-67031dd065be",
    "venue_id": 2289136,
    "creative_id": 1234,
    "state": "checkable",
    "distance": 111
  }
}


This object is detailed in the following table:

Request Attributes for Check-In

Attribute Type
Required/Optional
Description
place_id string
required
UUID of the check_in.
venue_id integer
required
ID of the place.
creative_id integer
optional
Platform-generated ID of the ad unit content; also called creative content.
state string
required
Check-in state. Can include:

checkable - Can check in to the place now.
alreadycheckedin_checkable - Checked in once, but the place supports multiple checkins.
alreadycheckedin_toofar - Already checked in to the place, and it is too far from the current location.
blocked_checkable - Customer is blocked from checking in to the place but it is with in check in radius.
blocked_toofar - Customer is blocked from checking in to the place and it is outside check in radius.
blocked_limithit - Customer is blocked from checking in to the place because they reached check in limit.
toofar - Place is too far from the current location.
distance integer
required
Distance away from being able to check-in

Response Object

In addition to a status key-value pair, the response object returned by the method contains two other objects, check_in and user, which are shown below:

▿ JSON Response

{
  "status": "ok",
  "check_in": {
    "place_id": "f3812fae-ebb1-11e5-953d-67031dd065be",
    "state": "alreadycheckedin_checkable",
    "can_check_in_again_at": "2016-03-02T17:08:29Z"
  },
  "user": {
    "id": "xxxxx"
  }
}


The following table provides details on the check_in object:

Response Attributes for Check In

Attribute Type Description
place_id string UUID of the customer.
state string Check-in state. Can include:

checkable - Can check in to the place now.
alreadycheckedin_checkable - Checked in once, but the place supports multiple checkins.
alreadycheckedin_toofar - Already checked in to the place, and it is too far from the current location.
blocked_checkable - Customer is blocked from checking in to the place but it is with in check in radius.
blocked_toofar - Customer is blocked from checking in to the place and it is outside check in radius.
blocked_limithit - Customer is blocked from checking in to the place because they reached check in limit.
toofar - Place is too far from the current location.
can_check_in_again_at string When the customer can check-in again at the place.

The second object returned is the user object.

Statuses and Errors

Since this method's statuses and errors are identical to what can be returned for the method that retrieves a list of places, see the "Statuses and Errors" section in Retrieve a List of Places for more information.

Devices API

Device objects allow you to define a customer-specific device such as a cell phone or laptop. These Device objects can be used for targeting based on platform, carrier and other attributes.

The primary function of this API is to provide a medium for passing in push notification tokens as they relate to any given customer per application. This is accomplished by creating new device objects for a customer and then assigning the device objects a push token attribute. The push notification token is required for a push notification campaign, which can be created using the SessionM Administration Portal. For more information, see Campaigns API.

This API provides the following methods:

Create or Update a Device

Adds or modifies attributes that describe a customer's device.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/:platform/devices/:device_id
POST /priv/v1/apps/:api_key/external/users/:external_id/:platform/devices/:device_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. Registering a device token ensures that the application or site can receive a push notification. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
platform Platform for the device. Can either be ios or android. Required on POST routes.
device_id Unique identifier for the device. On iOS, this is generally the idfa_id. For Android, this is generally the device_identifier. Required on POST.

Request Object

When this method runs, it passes in a request object that contains a device object, as shown below:

▿ JSON Request

{
  "device": {
    "token":"abcdefghijklmnopqrstuvwxyz",
    "sandbox":"true",
    "platform_version":"5.1",
    "model":"Transcender S3",
    "brand":"ACME",
    "manufacturer":"ACME Manufacturing",
    "screen":"1440x2560",
    "scale":1,
    "carrier_name":"Vistas",
    "mobile_country_code":310,
    "mobile_network_code":567
  }
}


This object is detailed in the table featured below.

All attributes are optional for this method. However, in order to use push notifications, the token is required as well as sandbox if the customer is in sandbox mode. For more information, Sandbox Mode.

Request Attributes for Device

Attribute Type
Required/Optional
Description
token string
required
Specifies the push notification token associated with this device; use this field for both Android and iOS device tokens.
sandbox boolean
optional
Indicates if this device is in sandbox mode. Applies to iOS platform. For more information, see Sandbox Mode.
platform_version string
optional
Represents the platform version for this device. For example, '9.0’ for iOS 9.0 or '5.1’ for Android 5.1.
model string
optional
Model name of this device.
brand string
optional
Brand name of this device.
manufacturer string
optional
Manufacturer of this device.
screen string
optional
Represents the screen resolution for this device.
scale integer
optional
Specifies the scale of the screen. Actual pixel resolution is the screen size times the scale.
carrier_name string
optional
Carrier providing service to this device.
mobile_country_code integer
optional
Mobile country code of this device.
mobile_network_code integer
optional
Mobile network code of this device.
Sandbox Mode

The sandbox attribute is iOS-specific and indicates if the application is in debug mode (as opposed to release mode).

For any given application/device combo on iOS, customers may want to store two devices: one sandbox; one not. This approach allows customers to send push notifications to devices running applications built from Xcode. Ad hoc release builds, or builds from the app store, are not sandbox.

Each device would have a unique token, and the request to send the push notification is sent to a different APNs endpoint if the device is in sandbox mode or not.

Response Object

Consider the following sample:

▿ JSON Response

{
  "device": {
    "source_application_id":"1253",
    "device_id":"idfa_id_or_device_identifier",
    "user_id":"uuid_for_user",
    "platform":"android",
    "token":"abcdefghijklmnopqrstuvwxyz",
    "sandbox":"true",
    "platform_version":"5.1",
    "model":"Transcender S3",
    "brand":"ACME",
    "manufacturer":"ACME Manufacturing",
    "screen":"1440x2560",
    "scale":1,
    "carrier_name":"Vistas",
    "mobile_country_code":310,
    "mobile_network_code":234
  }
}


This object is identical to the response object returned for a single-device GET. For more information, see the device object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Occurs when JSON data does not contain device object at the top level. Empty array returned if there are no devices.
invalid_platform Occurs if implementation not on iOS or Android.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a Device for a Customer

Retrieves a customer's specified device.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/devices/:device_id
GET /priv/v1/apps/:api_key/external/users/:external_id/devices/:device_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. Registering a device token ensures that the application or site can receive a push notification. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
device_id Unique identifier for the device. On iOS, this is generally the idfa_id. For Android, this is generally the device identifier. Required on POST and single device GET routes.

Request Object

Not applicable. However, device_id is required when specifying the GET endpoint.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a device object, which is shown below:

▿ JSON Response

{
  "device": {
    "source_application_id":"1253",
    "device_id":"idfa_id_or_device_identifier",
    "user_id":"uuid_for_user",
    "platform":"android",
    "token":"abcdefghijklmnopqrstuvwxyz",
    "sandbox":"true",
    "platform_version":"5.1",
    "model":"Transcender S3",
    "brand":"ACME",
    "manufacturer":"ACME Manufacturing",
    "screen":"1440x2560",
    "scale":1,
    "carrier_name":"Vistas",
    "mobile_country_code":310,
    "mobile_network_code":234
  }
}


This object is detailed in the following table:

Response Attributes for Device

Attribute Type Description
identifier string Identifier for the device. Utilized in response objects representing multiple devices.
source_application_id string Identifier for the application for which the device is registered.
device_id string Unique identifier for the device. On iOS, this is generally the idfa_id. For Android, this is generally the device_identifier. Required endpoint parameter on POST and single device GET routes.
user_id string Identifier for device customer.
platform string Platform for the device. Can either be iOS or Android. Required endpoint parameter on POST routes.
token string Push notification token associated with this device; use this field for both Android and iOS device tokens.
sandbox boolean Indicates if this device is in sandbox mode. Applies to iOS platform only. For more information, see Sandbox Mode.
platform_version string Platform version for this device. For example, '9.0’ for iOS 9.0 or '5.1’ for Android 5.1.
model string Model name of this device.
brand string Brand name of this device.
manufacturer string Manufacturer of this device.
screen string Screen resolution for this device.
scale integer Scale of the screen. Actual pixel resolution is the screen size times the scale.
carrier_name string Carrier providing service to this device.
mobile_country_code integer Mobile country code of this device.
mobile_network_code integer Mobile network code of this device.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Returned String Reason
device_not_found Occurs when device does not exist.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Devices for a Customer

Retrieves all of a customer's devices.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/devices
GET /priv/v1/apps/:api_key/external/users/:external_id/devicess

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. Registering a device token ensures that the application or site can receive a push notification. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a devices array, as shown below:

▿ JSON Response

{
    "status": "ok",
    "devices": [{
        "identifier": "android_test_device",
        "source_application_id": 18,
        "device_id": "android_test_device",
        "user_id": "a31b811a-d976-11e5-8d17-031b3bc47fce",
        "platform": "android",
        "platform_version": "5.1",
        "token": "abcdefghijklmnop",
        "sandbox": true,
        "model": "acme transcender s3",
        "brand": "ACME",
        "screen": "640x780",
        "scale": 2,
        "manufacturer": "ACME Manufacturing",
        "carrier_name": "Vistas",
        "mobile_country_code": 1,
        "mobile_network_code": "1"
    }, {
        "identifier": "android_test_device_2",
        "source_application_id": 18,
        "device_id": "android_test_device_2",
        "user_id": "a31b811a-d976-11e5-8d17-031b3bc47fce",
        "platform": "android",
        "platform_version": "5.1",
        "token": "abcdefghijklmnopqrstuvwzyz",
        "sandbox": true,
        "model": "acme transcender s3",
        "brand": "ACME",
        "screen": "640x780",
        "scale": 2,
        "manufacturer": "ACME Manufacturing",
        "carrier_name": "vistas",
        "mobile_country_code": 1,
        "mobile_network_code": "1"
    }]
}


This object contains multiple JSON blocks, each one specifying a specific device. For more information, see the table that documents a single device object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
device_not_found Occurs when device does not exist.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Events API

Events objects allow a third party to submit data representing specific actions taken by a customer. These actions are evaluated and acted upon based on the rules engine configuration for a specific campaign or outcome configured in the platform.

Some examples of customer-triggered events could include making a purchase, opening an application or moving to paperless billing. Event request objects provide the appropriate attributes for expressing these events.

Responses contain state data related to any completed actions defined by a specific event and its associated outcomes. Actions are defined in the SessionM Platform using the events they stream and any affiliated attributes. So, for example, the action “purchasing a hat” would use the purchase event being streamed to SessionM. The associated definition for the action would stipulate that the SKU must match whatever SKU corresponds to a hat.

Other actions might include:

This API provides the following methods:

Before you begin working with one of the methods listed above, consider the conceptual information detailed in in the overview below.

Overview

Events handle real-time and background event processing that feeds into the platform's action logic. This can be understood in terms of the requests and responses that define the transactions.

Request Data

Within the SessionM Platform, there are several types of event requests that can be processed via the API. This section provides a general description of these request data types:

This is the most basic event type. Examples of basic activity events range from digital engagement with content, such as opening an app or clicking on a web form, to other simple activity events, such as abandoning a shopping cart within a mobile app or on an e-commerce site. It is generally associated with metadata such as a count for the number of times it has occurred and the date of occurrence.

This event type signals location-specific activity. Common metadata includes location-specific information such as the device location of the event (longitude, latitude), geofence crossed, venue and time of the event. Internally, within the platform, each event can then be mapped to one or many venues, enabling the caller of the API to trigger location-specific content and messaging.

This event type signals purchase-specific activity. Internally, within the SessionM Platform, each event is mapped to a possible SKU-based purchase activity, enabling the caller of the API to trigger content and messaging based on SKU-level purchase events.

Response Data

All events submitted to the Events API are evaluated in real-time against loyalty program rules and campaigns associated with each event. When rule criteria is met based on the submission of the event, the API will respond with state information related to each associated rule.

Possible types of response data include:

Event submissions can trigger rules that alter customer data and profile attributes. For example, there can be status rules that update a customer’s “tier” when they have performed specific qualifying events.

Event submission can also trigger simple or complex actions. An action is defined by the client in the Platform using events and their attributes. During an event submission, the caller to the API may receive a list of actions that were completed because of the event. For example, an event may be associated to a simple action, such as the abandonment of a shopping cart. However things could be more complex, such as an action tracking the abandonment of a shopping cart for the 2nd time within a 24 hour period.

Event submissions can also trigger messaging or notifications. For example, a campaign may be configured to deliver a notification when a consumer makes their 2nd purchase within a 30-day period.

Currently the following message types are supported: "Push" and "Fullscreen."

Event submission can trigger eligibility for items of value, called incentives, which are configured within the platform. Current incentive types represent points, gift cards, offers, physical rewards, sweepstake entries and charity donations.

In some instances, a client cannot or does not wish to support real-time submission of events. In these cases, this API allows a client to submit events in batch.

Create an Event for a Customer

This API offers several types of request data for creating an event for a customer. They fall into three basic categories:

Ultimately, the response data for these events can be presented or utilized in what a customer experiences in an application or on a web site. For example, displaying to the customer the status of a campaign they've accessed or the progress they've made within it.

Endpoints Overview

This API offers three types of endpoints for posting an event. Note that each of the three has two versions of itself: one with an internal user_id and one with an external_id.

The first and most basic set of endpoints is designed to simply create one or multiple events, as shown below:

▿ REST Endpoints (Create Event(s))

POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/events


The second set of endpoints is designed to create one or multiple events for a specified campaign (via :ad_campaign_id), as shown below:

▿ REST Endpoints (Create Event(s) for a Campaign)

POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events


The third set of endpoints functions as the previous campaign-related endpoints do but they specify the campaign by a name (via :permalink) instead of an ID, as shown below:

▿ REST Endpoints (Create Event(s) for a Campaign by Name)

POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events

Request Data Specification

The characteristics listed above are represented in the request submitted to the Events API.

The primary object in the request is events, which is required and conforms to the following format conditions:

▿ Request Data (Event(s))

{"events": {"key": "by"}}


The elements of this format include:

Consider the following examples:

▿ Examples

{"event_name": 1}

{"event_name": {"qty": 1, "store": "A1B2"}}

{"event_name":
    [
      {"qty": 1, "store": "A1B2"},
      {"qty": 1, "store": "C3D4"}
    ]
}


The sections that follow document how to specify event attributes in both simple and complex submissions.

Simple Event Submissions

The following sample demonstrates a simple event submission:

▿ Simple Event Submission

{
  "events": {
    "purchase":{
      "qty":1,
      "date":"2016-08-01 14:02:58",
      "name": "PID324-1298B-G8H54"
    }
  }
}


The purchase event information conveys the type of event (purchase), the quantity of items purchased, the date of the purchase and the name, or SKU, of the item being purchased.

Complex Event Submissions

The complex event submission can mix and match attributes from the categories discussed in the previous section.

For example, the following sample request includes both purchase- and location-related attributes:

▿ Complex Event Submission

{
  "events": {
    "purchase": {
      "name": "SKU1",
      "qty": 2,
      "amount": 250,
      "store": "A1B2"
    }
  }
}


The purchase details are expressed with the name, qty, and amount attributes, while store specifies the location attribute.

This example shows the submission of point-of-sale transactional data. Note that the event can be matched against all running campaigns or against a particular campaign. You can use one of the following endpoints for that transaction:

▿ Endpoints Matching Event to Campaign

POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events


To check the event’s eligibility against running campaigns without processing the event, simply add qualify=true to the URL to check whether the event qualifies for a campaign:

▿ Endpoints Checking Event Eligibility Against Campaign

POST /priv/v1/apps/:api_key/users/:user_id/events?qualify=true


Note that if the occurred_on attribute is omitted, the time zone of the customer is used to determine event's current day.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events

POST /priv/v1/apps/:api_key/external/users/:external_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Campaign permalink that can be customer-defined or auto-generated.
ad_campaign_id Internal SessionM ad campaign ID.
qualify Checks the event’s eligibility against running campaigns without processing the event. Must be set to true to function.

Request Object

When this method runs, it can pass in a request object that contains the events object for three kinds of events:

Basic Activity Events

A basic activity event object is shown below:

▿ JSON Request for Basic Activity Event (Opening an App)

{
  "events": {
    "opened_app": {
      "by": 1,
      "date":"2014-08-01 14:02:58"
    }
  },
  "qualify": "true", "events": { "event_name": 1 }
}


Note that only rules associated with a campaign will be processed if ad_campaign_id or permalink is present in the request.

This object is detailed in the table below:

Request Attributes for Events - Basic Activity

Attribute Type
Required/Optional
Description
opened_app object
optional
Example of a custom event; can be defined for whatever event is being tracked. This event contains two attributes: by (an integer) to specify the count that increments each time the event occurs; and date (a string) to specify the time the event happened; defaults to current time in customer's time zone. Example:
{ "date": "2016-02-02T17:00:00Z", "events": { "event_name": 1 } }
read_only boolean
optional
For campaigns that require qualification, when this attribute is set to true, the event's outcome is previewed but NOT processed. Example:

{ "read_only": "true", "events": { … } }
qualify boolean
optional
Events sent on behalf of a customer who is not qualified for the campaign get saved but not processed; when qualify is set to true, the events are processed. Example:

{ "qualify": true, "events": { "event_name": 1 } }
Purchase Events

Purchase event objects are shown below:

▿ JSON Request for a Single Purchase

{
  "events": {
    "purchase": {
      "time": 865423786543,
      "timestamp": 865423786543,
      "name": "AQ45239866",
      "parent_name": "coffee",
      "description": "verbose description of the item",
      "qty": 5,
      "price_amount": 5050,
      "override_price_amount": 4050,
      "currency": "457",
      "channel": "InStore",
      "sub_channel": "Mobile",
      "store": "store identifier",
      "postal_code": "01875",
      "country": "USA",
      "transaction_id": "djj39991",
      "transaction_type": "purchase",
      "reload_type": "type of reload",
      "reload_amount": 5723,
      "subtotal_amount": 4500,
      "amount": 5050,
      "location": {
        "latitude": 754.897,
        "accuracy": 494.485
      }
    }
  }
}

▿ JSON Request for Multiple Purchases

{
  "events": {
    "event_name": [
      {
        "name": "SKU1",
        "qty": 2,
        "amount": 250,
        "store": "A1B2"
      }
      {
        "name": "SKU2",
        "qty": 1,
        "amount": 370,
        "store": "A1B2"
      }
    ]
    }
  }


Attributes for the purchase object and the event_name array are detailed in the following table:

Request Attributes for Events - Purchase Activity

Note that when using purchase event attributes, all other payload attributes will be dismissed.

Attribute Type
Required/Optional
Description
time integer
required
POSIX or epoch time. Time specified in seconds since January 1, 1970 UTC. Default: Date or current time in customer's time zone if not present in payload.
timestamp integer
optional
Duplicate of time.
name string/
required
SKU. Unique identifier for the item in the product catalog.

Default:
event_name if not present in payload

Example:
a1b2c3
parent_name string
optional
SKU of the modifier. For example, "name":"hazelnut_syrup", "parent_name":"coffee".
description string
optional
Verbose description of the item.
qty integer
required
The number of items.

Example:
1
Default is 0.
price_amount decimal
optional
The price of the item represented in cents. Cost of the item multiplied by "qty" value.

Example:
199
override_price_amount decimal
optional
What the customer actually paid; not the price_amount, which is the original cost.
currency string
optional
Currency code. Used only for logging.
channel string
optional
Source of the transaction. Store channel used to submit the transaction.

Example:
InStore
sub_channel string
optional
Sub of the source specified as channel. Store sub channel used to submit the transaction.

Example:
Mobile
store string
required
Unique identifier of the store where the transaction occurred.

Example:
A1B2C3
postal_code string
optional
Postal code associated with store.
country string
optional
Three-letter code for country associated with store.
transaction_id string
optional
Unique identifier of the transaction. Used by the event processor for idempotency, if supplied results of the transaction can be retrieved from the event transactions API.

Example:
aaa-bbb-111-222
transaction_type string
optional
Indicates type of transaction: reload, purchase or redemption.
reload_type string
optional
Type of reload.
reload_amount decimal
optional
Amount reloaded.
subtotal_amount decimal
required
Subtotal amount of the entire basket without tax.
amount decimal
required
Total amount represented in cents for the specified transaction. (Actual amount customer paid for item(s).)

Default:
1 if not present in payload.
location hash
optional
Current location of the customer. See table detailing the location object.

Request Attributes for Location Object within Purchase Activity

Attribute Type
Required/Optional
Description
latitude decimal
optional
Latitude value for customer's location.
longitude decimal
optional
Longitude value for customer's location.
accuracy decimal
optional
Phone's accuracy for the specified location. For example "50" indicates that the associated latitude/longitude coordinates could be as much as 50 meters off.
Location Events

A location event object is shown below:

▿ JSON Request for User Performed Location Event

{
  "events": {
    "location_event_name": {
      "date":"2014-08-01 14:02:58",
      "location": {
        "latitude": "42.3501",
        "longitude": "-71.0414"
      },
      "geofence" :{
        "latitude": "42.35017",
        "longitude": "-71.041731",
        "radius": 100
      },
      "data": {
        "venue_id": "741184"
      }
    }
  }
}


Attributes for these objects are detailed in the following tables:

Request Attributes for Events - Location

Attribute Type
Required/Optional
Description
date datetime
optional
Date and time of location event.
location object
optional
Current location of the customer. See table detailing the location object.
geofence object
optional
Contains latitude and longitude attributes, which are both floats for the related geofence coordinates. Also contains radius, an integer that defines the geofence radius.
data object
optional
Contains the venue_id of the associated location.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the following attributes and objects:

Consider the following samples:

▿ JSON Response for Purchase Event with Qualify Parameter NOT Set

{
    "status": "ok",
    "available_points": 120,
    "notifications": [
        {
            "id": "2cd1c9f8-8471-11e8-8d01-7ed232d1fae9",
            "type": "message",
            "campaign_id": 313,
            "behavior_name": "first_behavior_payload_0",
            "data": {
                "action_type": "message",
                "url": "http://apackard-mbp.i.sessionm.com:3000/apps/e154a4ccba7b84031a1e6fb920acb0f9391cf0c0/users/1d27ebba-1558-11e7-8838-c9b232d1fae9/ads/704",
                "message": "Tap Here",
                "payload": {
                    "gift_card_code": "883883-3938292-2928282",
                    "gift_card_name": "$5 Off Next Purchase"
                }
            }
        }
    ],
    "user": {
        "available_points": 120,
        "tier": "silver"
    },
    "behaviors": {
        "first_behavior": {
            "type": "composite",
            "points": 0,
            "achieved": 2,
            "can_skip": true,
            "skipped": 0,
            "max_times_repeatable": null,
            "max_times_repeatable_per_period": null,
            "period": 86400,
            "min_time_between_events": null,
            "consecutive": false,
            "goals": {
                "d1f15666_8470_11e8_87a8_427632d1fae9": {
                    "type": "goal",
                    "points": 4,
                    "completed": false,
                    "required": true,
                    "earn_count": 1,
                    "group_id": "0",
                    "progress": {
                        "event_name": "d1f15666-8470-11e8-87a8-427632d1fae9",
                        "type": "count",
                        "points": 4,
                        "max_times_repeatable": null,
                        "max_times_repeatable_per_period": null,
                        "period": 7776000,
                        "min_time_between_events": null,
                        "min_time_between_events_count": 1,
                        "consecutive": false,
                        "achieved": 2,
                        "current_count": 0,
                        "total_count": 1,
                        "deltas": {
                            "current_count": 1,
                            "achieved": 1
                        }
                    }
                }
            },
            "groups": {
                "0": {
                    "type": "group",
                    "current_count": 0,
                    "total_count": 1,
                    "num_goals": 1,
                    "completed": false
                }
            },
            "deltas": {
                "achieved": 1
            }
        }
    },
    "deltas": {
        "d1f15666_8470_11e8_87a8_427632d1fae9": {
            "current_count": 1,
            "achieved": 1
        },
        "first_behavior": {
            "achieved": 1
        }
    },
}

Note that the purchase event response above is nearly identical to the response for an activity event. The difference is that the purchase event's value for event_name is a random string ("d1f15666-8470-11e8-87a8-427632d1fae9", shown above), while the activity event's value for event_name is meaningful.

▿ JSON Response for Purchase Event with Qualify Parameter Set

{
    "status": "ok",
    "available_points": 120,
    "notifications": [],
    "user": {
        "available_points": 120,
        "tier": "silver"
    },
    "behaviors": {
        "first_behavior": {
            "type": "composite",
            "points": 0,
            "achieved": 2,
            "can_skip": true,
            "skipped": 0,
            "max_times_repeatable": null,
            "max_times_repeatable_per_period": null,
            "period": 86400,
            "min_time_between_events": null,
            "consecutive": false,
            "goals": {
                "d1f15666_8470_11e8_87a8_427632d1fae9": {
                    "type": "goal",
                    "points": 4,
                    "completed": false,
                    "required": true,
                    "earn_count": 1,
                    "group_id": "0",
                    "progress": {
                        "event_name": "d1f15666-8470-11e8-87a8-427632d1fae9",
                        "type": "count",
                        "points": 4,
                        "max_times_repeatable": null,
                        "max_times_repeatable_per_period": null,
                        "period": 7776000,
                        "min_time_between_events": null,
                        "min_time_between_events_count": 1,
                        "consecutive": false,
                        "achieved": 2,
                        "current_count": 0,
                        "total_count": 1,
                        "deltas": {
                            "current_count": 1,
                            "achieved": 1
                        }
                    }
                }
            },
            "groups": {
                "0": {
                    "type": "group",
                    "current_count": 0,
                    "total_count": 1,
                    "num_goals": 1,
                    "completed": false
                }
            },
            "deltas": {
                "achieved": 1
            }
        }
    },
    "deltas": {
        "d1f15666_8470_11e8_87a8_427632d1fae9": {
            "current_count": 1,
            "achieved": 1
        },
        "first_behavior": {
            "achieved": 1
        }
    },
    "qualified": true,
    "state": "qualified"
}
Notifications Object

This table below provides details on the notifications object, which will contain data when the qualify parameter on the endpoint is unset or set to false:

Response Attributes for Notifications Object Associated with Events

Attribute Type Description
id integer Unique identifier.

Example:
ad stat id.
type string Ad type.

Example:
message,in_app)
campaign_id integer Ad campaign identifier.
data object The additional data associated with the notification message payload.
action_type string Type of action.

Example:
message,open_ad
url string The URL of the message.
message string The body of the message.
payload object The additional data associated with the ad unit; also called creative content.
Behaviors Object

This following table provides details on the behaviors object:

Response Attributes for Behaviors Object Associated with Events

Attribute Type Description
event_name string Name of the event.
type string Type of the object (composite, count, unique).
points integer Amount of points completing the action is worth.
achieved integer Total times the action has been completed by a given customer.
can_skip boolean Indicates whether an action can be skipped or not (true).
skipped integer Integer value asssociated with skipped action.
max_times_repeatable integer Number of times an action can be achieved by a given customer overall.
max_times_repeatable_per_period integer Number of times an action can be achieved by a customer within a defined period.
period integer Time period in which you want to count events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds.
min_time_between_events integer Min time period between events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds.
min_time_between_events_count integer
consecutive boolean Indicator wether events need to happen on consecutive days
current_count integer Event count towards completing the action.
total_count integer Event count required for completing the action.
goals object Actions associated with composite action. See dedicated table below.
deltas object Changes attributed to the request. See dedicated table below.
groups object Action groups associated with the composite action. See dedicated table below.

The following format applies to this object:

{ behaviors: { behavior_name: {} } }

Note: If ad_campaign or permalink is passed in the request, behaviors are scoped to the ad campaign.

Response Attributes for Goals Object

The goals object contains changes attributed to the Events request and reflects only composite progress.

Format as follows:{ goals: { behavior_name: {} } }

Attribute Type Description
event_name string Name of the event.
type string Type of the object ("goal")
points integer Amount of points completing the goal is worth.
completed boolean Indicator whether the desired customer action (sometimes referred to as a goal) has been completed.
required boolean Indicator whether the completion of the desired customer action is required to complete the composite action.
earn_count integer Customer action (sometimes referred to as a goal) count required to complete the composite action.
group_id integer Index of the group the action belongs to within the composite action.
progress object Contains all the metadata of the action and associated counts. In effect, a record of the customer's interactions with the action. This object's details about the progress of the action are the same as those attributes described for the Behaviors object associated with a basic activity.

Format:
{progress: {} }

For more information, see the "Response Attributes for Behaviors Object Associated with Events" table above.

Response Attributes for Groups Object

The groups object contains changes attributed to the Events request and reflects only composite progress.

Format as follows:{ groups: { group_index: {} } }

Attribute Type Description
type string Type of the object ("group").
current_count integer Completed goal count within the group.
total_count integer Total count required to complete the group.
num_goals integer Number of actions within the group.
completed boolean Indicator whether the group has been completed.
Deltas Object

This following table provides details on the deltas object:

Response Attributes for Deltas Object

The deltas object contains changes attributed to the Events request.

Attribute Type Description
current_count integer Change in current_count.
achieved type Achieved changed.
data array List of action pivots for a given customer. Reflects only unique progress

Example:
['store1','store2']
current_count integer Count of action pivots towards earning the action. Reflects only unique progress.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_event_data Event data is missing from request.
No_active_campaign_found No campaign was found matching the request criteria.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Events for a Customer

Retrieves events for a customer, including reward balances as well as action and progress data for the customer's events

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/events

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an attribute and another object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "available_points": 0,
  "behaviors": {
    "behavior_name": {
      "event_name": "event_name",
      "type": "count",
      "max_times_repeatable": "nil",
      "max_times_repeatable_per_period": "nil",
      "min_time_between_events": "nil",
      "consecutive": false,
      "achieved": 0,
      "current_count": 0,
      "total_count": 2
    }
  }
}


It begins with a status key-value pair that provides the status of the transaction. The next line in the response specifies the available_points key-value pair, which indicates how many loyalty points are available to the customer.

The response object also contains the behaviors object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Timeline APIs

These APIs support the creation and maintenance of timeline services for an organization. With respect to this service, an event can be defined as an arbitrary action that occurred at a specific time, anchored to an arbitrary object and contains data attributes specific to this particular type of action.

As you consult the conceptual discussions and the tables that detail JSON requests and responses, bear in mind that timelines utilize a collection of objects and attributes that contain the word "stream." For example, consider these object names: stream, stream_view and stream_type. When this site describes a timeline attribute or object, it uses these names. However, when discussions are more conceptual and descriptive in nature, this site uses the word "timeline." Of course this site always utilizes the literal names for all objects and attributes in timeline-related sample code or their associated references; in these cases, the term "stream" is never replaced with "timeline."

In more concrete terms, an implementation of the timeline service could be a member statement that represents customer activity. For example, an event could have the following characteristics:

Part of the functionality offered by this collection of APIs is the ability to create event types and categories, or groupings, of event types. The Timeline Event Types API allows you to build out and maintain event types as well as associate rendering templates to them.

Timeline services can reflect a variety of timelines, including those for customer activity, campaign activity, enduser communication and Point of Sale (POS) activity.

You can use the Timeline Service API to build and maintain the service. When designing your timeline service, do so in a generic manner. This approach makes it easy to define additional event timelines with different event definitions and levels of granularity that require a minimal development effort. One of the functions this API offers is the ability to consume raw data from external devices that are generating events. Related methods can interpret raw event data and render it in specific customer contexts. With this API, you can publish an event and retrieve a page of events for a particular event timeline view.

Each service can record types of temporal events with varying sets of data attributes per event type. Doing so generates a timeline of events in reverse chronological order that can be accessed in a paged manner.

An event timeline can be of infinite size. However, the Timeline Configuration API includes methods that can constrain a very large timeline with views that read from the timeline service and inject context into the raw event data being presented. This API includes methods for creating event templates and rendering contexts for these views.

Views allow for paging through a timeline, either rendered literally as pages of events or shown with an “infinite scroll” mechanism. They can reflect different levels of granularity, and individual events within them can appear in multiple views. For example, the same event can be included in the view for a particular customer’s events, and also show up in a view tied to a particular campaign.

This section contains the following discussions:

If you want information on working with events, see the Events API.

Timeline APIs Architecture

The Timeline APIs architecture features object entities that reflect the three APIs that enable the programmatic capture of event histories, or timelines. These entities can be best understood in the following two sections, with each discussion rooted in a diagram:

Event Definition

Before you can present timelines of customer events, you must define the events being represented in the timeline. Events are the digital representation of a customer's activity that gets passed to SessionM as data. Generally they can be defined as one of the three types: engagement (or activity), location and purchase.

SessionM offers the Event Types API so you can build out a hierarchy of event metatdata. In short, event categories contain event types which define events. The following diagram depicts these entities:

Event stream objects 2

The Event Categories box shown at the top of the diagram represents a category that aggregates a set of event types into a single, common grouping. In this case, the event category is "Purchases." It contains three event types, which are shown in the Event Types box located in the middle of the diagram. Each event type defines the kind of event that is being expressed; in this example, the purchase event types include "Returned Item," "Voided Transaction" and, of course, "Purchased Item."" Each of these types represents a result that can follow from a purchase:

All fit logically within the event category, "Purchases."

The bottom box of the diagram depicts the Event object type. Unlike the other boxes in the diagram, the Event box shows the attributes defined by both the higher level types and the attributes that are critical to defining what an event is. Inherited attributes include the event category and the event type, which are shown toward the top of the event box. Other attributes include identifiers, a timestamp and the heart of the event, a payload. It is the payload that expresses perhaps the most familiar characteristics of a purchase event: What the item is, its size, its price and its associated tax.

Event Display

With event categories, event types and events defined, determine how timelines of events can be displayed. Timelines can reflect event histories of a variety of actors, however, the current SessionM implementation features those reflecting customer events.

This customer event timeline is populated from events generated by customers using external devices. Supported by methods available in the Timeline Service API, the raw data from these events can be published as timeline objects in the SessionM Platform. Once data is in residence as a user_event_stream, it can be configured for display via timeline views and rendering contexts. The diagram show below depicts these entities and their relationships:

Event stream objects 1

Note that the publishing of raw external event data as a timeline is not presented in the diagram above; it happens outside of the platform.

Event data consumed from external sources resides in the bottom box of the diagram, which is labeled "Timelines." In this case, the timeline shown is a customer timeline. Since the number of events in any timeline can be quite large, timeline views determine what subset of events will be presented, a specification that is shown in the middle box of the diagram, "Timeline Views." Two views are shown; one as a customer member statement and one as a customer service agent member statement. Each view expresses its own collection of events, all of which are defined by particular event types and represented as multiple Event boxes located between the Timelines and Timeline Views layers.

While timelines do provide a mechanism for narrowing which events will be shown in a timeline, event templates and rendering contexts define how those events will appear. The top box of the diagram labeled "Timeline Rendering Contexts" contains two rendering contexts, each of which specifies context for a view being presented in an associated template. In this case, the rendering contexts include one for customers engaged in a iOS-based mobile experience and the other for customer service agents accessing the platform's customers module in the UI. For both contexts, event templates have been defined, along with their association to an event type and a rendering context, as shown in multiple Event Template boxes located between the Timeline Views and the Timeline Rendering Contexts layers.

Timeline Event Types API

The Timeline Event Types API offers a collection of endpoints that build and manage event types for events shown in an event timeline. Event types are kinds of actions; they name and define the actions that are common to your organization and, often, customers.

Maintained in the SessionM Platform, each event type defines the metadata for each event that can occur; for example, "Purchased Item XYZ" or "Opened an Email." A grouping of event types, however, are event categories; for example, "Customer Actions." Event categories are an optional way of defining a set of related event types. Finally, an event itself is an instance of an event type; for example, "Customer ABC Purchased Item XYZ."

In addition to managing the types and categories for events, this API includes endpoints for creating and managing rendering templates for the event types. Templates can serve a variety of contexts, including:

This API provides the following methods:

Create an Event Category

Create an event category for grouping a set of event types together.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/categories
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains an category object, as shown below:

▿ JSON Request

{
  "category": {
    "name": "Points Economy",
    "description": "Points Economy"
  }
}


This object is detailed in the following table:

Request Attributes for Category

Attribute Type
Required/Optional
Description
name string
required
Timeline view name. For example, "Acme Inc.'s member statement".
description string
optional
Timeline view description. For example, "Acme Inc.'s member statement, defined as a view on the user timeline."
Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_category object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "event_category": {
    "id": 9,
    "name": "Points Economy",
    "slug": "POINTS_ECONOMY",
    "description": "Points Economy",
    "created_at": "2017-08-24T17:15:00Z",
    "updated_at": "2017-08-24T17:15:00Z"
  }
}


This object is detailed in the following table:

Response Attributes for Category

Attribute Type Description
id integer Database identifier for the event category.
name string Name for the event category.
slug string Permalink generated from the name of the event category. For example, "POINTS_ECONOMY".
description string Description of event category.
updated_at datetime ISO8601 formatted timestamp when the timeline category was updated.
created_at datetime ISO8601 formatted timestamp when the timeline category was created.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create an Event Type

Create an event type for the kind of action that occurred, such as “Purchased” or “Opened Email."

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
Request Object

When this method runs, it passes in a request object that contains a event_type object, as shown below:

▿ JSON Request

{
    "event_type": {
        "name": "New Name",
        "description": "new description",
        "event_stream_event_category_id": 1
    }
}


This object is detailed in the following table:

Request Attributes for Event Type

Attribute Type
Required/Optional
Description
name string
required
Name of the event type for the kind of activity that occurred.
description string
optional
Description of event type.
event_stream_event_category_id integer
required
Identifier for the associated event category.

▿ JSON Response

{
    "status": "ok",
    "event_type": {
      "id": 1,
      "name": "Name",
      "slug": "NAME",
      "description": "Description",
      "event_stream_event_category_id": 1,
      "event_stream_stream_id": 1
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains a event_type object, as shown below:

▿ JSON Response

{
    "status": "ok",
    "event_type": {
      "id": 1,
      "name": "Name",
      "slug": "NAME",
      "description": "Description",
      "event_stream_event_category_id": 1,
      "event_stream_stream_id": 1
  }
}


This object is detailed in the table below:

Response Attributes for Event Type

Attribute Type Description
*id integer Identifier for the event type.
name string Name of event type.
slug string Permalink generated from the name of the event type.
description string Description of event type.
event_stream_event_category_id integer Identifier for the timeline category associated with the event type.
event_stream_stream_id integer Identifier for the timeline associated with the event type.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Rendering Template

Create a rendering template, mapping an event template to a specific rendering context. The context specifies the environment in which events should be rendered and targets a particular template to that environment.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
event_type_id Identifier for the event type.
Request Object

When this method runs, it passes in a request object that contains a rendering_template object, as shown below:

▿ JSON Request

{
  "rendering_template": {
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}


This object is detailed in the following table:

Request Attributes for Rendering Template

Attribute Type
Required/Optional
Description
event_stream_event_template_id integer
required
Identifier of the associated event template.
event_stream_stream_view_id integer
required
Identifier of the associated event timeline view.
event_stream_rendering_context_id integer
required
Identifier of the associated rendering context.
version integer
optional
Version of the rendering template.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_template object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "rendering_template": {
    "id": 4,
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}


This object is detailed in the table below:

Response Attributes for Rendering Template

Attribute Type Description
id Database identifier for the rendering template.
event_stream_event_template_id integer Identifier of the associated event template.
event_stream_stream_view_id integer Identifier of the associated event timeline view.
event_stream_rendering_context_id integer Identifier of the associated rendering context.
version integer Version of the rendering template.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Event Categories

Retrieve all event categories for an organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/categories
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many event_category objects. Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "result": [
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 30,
           "name": "Points Economy 1",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_1",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    },
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 31,
           "name": "Points Economy 2",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_2",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    },
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 32,
           "name": "Points Economy 3",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_3",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    }
  ]
}


The array is empty if no categories exist. When present, the event_category object can contain several attributes. For more information, see the event_category object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Rendering Templates

Retrieve all existing rendering templates for a specified event type.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
event_type_id Identifier for the event type.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a templates array, which is a hash array of one or many rendering_template objects. Consider the followig sample:

▿ JSON Response

{
  "status": "ok",
  "templates": [{
      "rendering_template": {
        "id": 1,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 1,
        "version": 1
      }
    },
    {
      "rendering_template": {
        "id": 2,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 2,
        "version": 1
      }
    },
    {
      "rendering_template": {
        "id": 3,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 3,
        "version": 1
      }
    }
  ]
}


The array is empty if no templates exist. When present, the rendering_template object can contain several attributes. For more information, see the rendering_template object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_rendering_template_found Specified rendering template for event category, or type, cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Event Type

Retrieve a specified event type with all of its related attributes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
event_type_id Identifier for the event type.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_type object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}


This object is detailed in the table below:

Response Attributes for Event Type

Attribute Type Description
id integer Database identifier for the event category, or type.
name string Name for the event category, or type.
slug string Slug for event category, or type.
description string Description of event category, or type.
event_stream_event_category_id integer Identifier for the associated event category, or type.
event_stream_stream_id integer Identifier of the associated timeline.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_event_type_found Specified event type, or category, cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update an Event Category

Update an event category that groups a set of event types together.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT  /priv/:api_version/apps/:api_key/timelines/categories/:category_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
category_id Identifier for an event category.
Request Object

When this method runs, it passes in a request object that contains a category request object as shown below:

▿ JSON Request

{
  "category": {
    "name": "Points Economy",
    "description": "Points Economy"
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_category object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "event_category": {
    "id": 9,
    "name": "Points Economy",
    "slug": "POINTS_ECONOMY",
    "description": "Points Economy",
    "created_at": "January 30, 2017 10:22",
    "updated_at": "January 30, 2017 10:22"
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_event_category_found Specified event category cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Rendering Template

Update a specified rendering template for an event type.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT  /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates/:template_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
event_type_id Identifier for the event type.
template_id Identifier for a rendering template.
Request Object

When this method runs, it passes in a request object that contains a rendering_template object, as shown below:

▿ JSON Request

{
  "rendering_template": {
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_template object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "rendering_template": {
    "id": 4,
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_rendering_template_found Specified rendering template cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update an Event Type

Update an event type, modifying attributes such as its name and description.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
event_type_id Identifier for the event type.
Request Object

When this method runs, it passes in a request object that contains an event_type object, as shown below:

▿ JSON Request

{
  "event_type": {
    "name": "Earned Achievement \"Free Hamburger\"",
    "description": "Earned Achievement \"Free Hamburger\""
  }
}


This object is detailed in the table below:

Request Attributes for Event Type

Attribute Type
Required/Optional
Description
name string
optional
Name of the event type.
description string
optional
Description of the event type.

▿ JSON Response

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_type object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_event_category_found Specified event category, or type, cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Timeline Service API

A timeline service can record various types of temporal events, each with its own different set of data attributes. It allows developers to access them as a timeline of infinite size. You can use the service to define different kinds of timelines; while a user event timeline is quite typical, you can also create a campaign timeline. Having multiple timelines allows you to keep events logically separated along service boundaries and not easily intermingled. The Timeline Service API offers a collection of endpoints that build and manage an event timeline service.

Before timelines can exist on the SessionM Platform, the events being generated from external sources or devices must be captured. This API supports this task by providing methods that manage the consumption of events published by external devices and interpret raw event data so it can be rendered in a specific customer context.

This API provides the following methods:

Publish an External Event into a Timeline

Publish events generated from external devices outside of the SessionM Platform into timelines in either a synchronous or asynchronous mode. The raw data generated by events is represented by user_event_stream objects specified on the platform.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints (Async and Sync)

POST /v1/apps/:api_key/users/:user_id/timelines/:stream_id
POST /v1/apps/:api_key/external/users/:external_id/timelines/:stream_id
POST /v1/apps/:api_key/users/:user_id/timelines/stream_type_slug
POST /v1/apps/:api_key/external/users/:external_id/timelines/stream_type_slug
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
stream_id Integer that identifies the timeline.
stream_type_slug Human-readable value that identifies the timeline.
Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

▿ JSON Request

{
  "transactional": false,
  "stream_type": "USER",
  "event_type": "PURCHASE_TRANSACTION",
  "timestamp": "2017-06-05 12:30:00",
  "payload": {
    "value": "17.00",
    "num_points": "17"
  }
}


This object is detailed in the following table:

Request Attributes

Attribute Type
Required/Optional
Description
transactional boolean
optional
If true, event published directly; if false, which is generally the case, event is saved to an event timeline log file.
stream_type string
required
Timeline type.
event_type string
required
Event type, such as PUSH_MESSAGE_OPENED, LOYALTY_RULE_ACHIEVED, POINTS_COMPED or PURCHASE_TRANSACTION.
target_id integer
optional
Anchored object by which to filter events. E.g., player_id.
payload JSON
required
Arbitrary semi-structured data related to the event instance. Any type of event context is possible. For example, if the event context is "points deducted," then the payload would be the number of points. Or, if the context is a purchase event, than the attributes might be "price" and "quantity."
Response Object

In addition to a status key-value pair, the response object returned by the method contains a result object, which can contain the saved attribute. If this boolean is set to true, the event has been published.

Consider the following sample:

▿ JSON Response

{
  "status": "ok",
  "result": {
    "saved": true
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Events for a Single View

Retrieves an array of events in a timeline view that reflects a specific user or type of user. The event data returned represents a wide range of event activity, which can vary depending upon what type of user is performing the events. For example, the events in a view associated with an enduser, or customer, making a purchase differs a great deal from an administrator creating new event types.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW
GET /v1/apps/:api_key/users/:user_id/timelines/NEW_VIEW
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for user who performed the event actions.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
context_slug Permalink that defines the event-rendering environment. Use this in lieu of a rendering template to display view in the SessionM Platform UI. This parameter targets an event template, providing information on how to render events. Note that event templates are tied to an event timeline rendering context.
since Starting timestamp from which to query for subsequent events. If no value is passed, all events are returned.
count Number, or limit, for events to return.
event_category_id Identifier for event category to filter on.
event_types Event Type(s) associated with view.
target_id SessionM ID that is synonymous with player_id.

If you want to filter the view, you can pass in filters via the endpoint. Specify the endpoint by drawing from a set of possible filter types, all listed below with corresponding sample data:

Combining several of these parameters together might produce the following endpoint:

GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW?count=1&since=1530045547&event_types=12,13,14&filter[event_category_id]=123

Note that an important part of this endpoint's syntax is the interplay between the since and count attributes to produce pagination. For example, you might return 300 pages of a view with the following calls:

Views rendered in the SessionM UI derive from the activity log for the platform. The value for this view is end_user_member_statement with a context of mmc_customer_campaigns.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the result array, as shown below:

▿ JSON Response

{
  "status": "ok",
  "result": [
    {
      "event_stream_stream_id": "735c10bc-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 186,
      "event_stream_event_type_id": 449,
      "target_id": 600,
      "timestamp": 1467830700000,
      "created_at": 1502377143000,
      "event_stream_payload": {
        "tier_level": "Silver",
        "rewards_system_id": "6",
        "event_category_slug": "TIERS",
        "event_type_slug": "TIER_ADVANCED",
        "event_category_name": "TIERS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "730646b6-7ddc-11e7-96f4-ff5e1b0abf72",
        "event_type_name": "Tier Advanced",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " Tier advanced to Silver"
        }
      ]
    },
    {
      "event_stream_stream_id": "738c2170-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 181,
      "event_stream_event_type_id": 441,
      "target_id": 600,
      "timestamp": 1467801120000,
      "created_at": 1502377144000,
      "event_stream_payload": {
        "reason_code": "Reason Code 103: Good Will  +100 points",
        "num_points": 100,
        "rewards_system_id": "6",
        "event_category_slug": "POINTS",
        "event_type_slug": "POINTS_COMPED",
        "event_category_name": "POINTS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "72fbed9c-7ddc-11e7-8aec-3984f8bf80a4",
        "event_type_name": "Points Comped",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " Reason Code 103: Good Will  +100 points +100.0 points"
        }
      ]
    },
    {
      "event_stream_stream_id": "7303b788-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 181,
      "event_stream_event_type_id": 442,
      "target_id": 600,
      "timestamp": 1467744300000,
      "created_at": 1502377143000,
      "event_stream_payload": {
        "num_points": 100,
        "rewards_system_id": "6",
        "event_category_slug": "POINTS",
        "event_type_slug": "POINTS_EARNED",
        "event_category_name": "POINTS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "72e9007e-7ddc-11e7-8486-43b6f8bf80a4",
        "event_type_name": "Points Earned",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " +100.0 points"
        }
      ]
    }
  ]
}


This object is detailed in the following table:

Response Attributes for Result

Attribute Type Description
event_stream_stream_id string Identifier for the timeline.
event_stream_event_category_id integer Identifier for event category used in filtering.
event_stream_event_type_id integer Identifier for event type used in filtering.
target_id integer Anchored object used in event filtering, player_id.
timestamp datetime UTC timestamp of when event occurred. May be set to arbitrary datetime in the past.
created_at datetime UTC timestamp of when event was recorded to data store.
event_stream_payload object Arbitrary semi-structured data related to the event instance and used to render events.
contexts array Rendered events which are shown to the user. For more information, see the Response Attributes for Contexts table below.

Response Attributes for Contexts

Attribute Type Description
id integer Rendering context identifier.
name string Rendering context name.
value string Rendered event.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Timeline Type

Create a timeline type.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/stream_types
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains a stream_type object, as shown below:

▿ JSON Request

{
    "stream_type": {
        "name": "Name",
        "description": "Description"
    }
}


This object is detailed in the following table:

Request Attributes for Stream Type

Attribute Type
Required/Optional
Description
name string
required
Name of the timeline type.
description string
optional
Description of timeline type.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_type object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "stream_type": {
      "id": 41,
      "name": "Name",
      "slug": "NAME",
      "description": "Description"
  }
}  


This object is detailed in the following table:

Response Attributes for Stream Type

Attribute Type Description
id integer Identifier for timeline.
name string Name of timeline.
slug string Permalink that identifies the timeline, or stream, type.
description string Description of timeline.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Timeline Service

Create an timeline service for the current organization. Doing so creates a kind of super view of all events occurring in the timeline for the organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/streams
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

▿ JSON Request

{
  "stream": {
    "event_stream_stream_type_id": 1
  }  
}
Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

▿ JSON Request

{
  "stream": {
    "event_stream_stream_type_id": 1
  }  
}


This object is detailed in the following table:

Request Attributes for Stream

Attribute Type
Required/Optional
Description
event_stream_stream_type_id string
required
Identifier for the event timeline.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many stream objects. Consider the sample below:

▿ JSON Response

{
  "status": "ok",
  "stream": {
    "id": 7,
    "organization_id": 4,
    "event_stream_stream_type_id": 7,
    "created_at": "2017-01-09T10:27:25-05:00",
    "updated_at": "2017-01-09T10:27:25-05:00"
  }
}


The array is empty if no timelines exist. When present, the stream object can contain the following details:

Response Attributes for Stream

Attribute Type Description
id integer Timeline database identifier.
organization_id integer Identifier of the associated organization.
event_stream_stream_type_id integer Identifier of the associated timeline.
created_at datetime ISO8601 formatted timestamp of when the timeline was created.
updated_at datetime ISO8601 formatted timestamp of when the timeline was updated.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve All Timeline Services

Retrieves all existing timeline services for the current organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/streams
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many stream objects. Consider the sample below:

▿ JSON Response (Multiple Timelines Found)

{
  "status": "ok",
  "streams": [
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 51,
            "id": 49,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  },
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 52,
            "id": 50,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  },
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 53,
            "id": 51,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  }
  ]
}


The array is empty if no timelines exist. When present, the stream object can contain several attributes.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve a Specified Timeline Service

Retrieves a specified timeline service.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/streams/:timeline_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "stream": {
    "id": 12,
    "organization_id": 17,
    "event_stream_stream_type_id": 12,
    "created_at": "2017-01-30T07:58:18-05:00",
    "updated_at": "2017-01-30T07:58:18-05:00"
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_stream_found Specified timeline cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Timeline Service

Update an existing timeline service.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/:api_version/apps/:api_key/timelines/streams/:timeline_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

▿ JSON Request

{
  "stream": {
    "event_stream_stream_type_id":  1
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "stream": {
    "id": 12,
    "organization_id": 17,
    "event_stream_stream_type_id": 12,
    "created_at": "2017-01-30T07:58:18-05:00",
    "updated_at": "2017-01-30T07:58:18-05:00"
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_stream_found Specified timeline cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Timeline Configuration API

The Timeline Configuration API supports the creation and retrieval of timeline views, which refine the contents presented by a timeline service by providing specific views, or subsets, of the entire timeline.

Each timeline can have multiple stored “view" definitions. For example, a customer's member statement is a particular view of an all-encompassing customer timeline.

This API also offers objects that create event templates and their corresponding rendering contexts. The event template model defines how an event should be rendered in a given context. The rendering context model is a global list of contexts in which to render events. It targets a template to a type of environment in which to render. For example, mobile:ios.

This API provides the following methods:

Create a Timeline View

Create a view of a specific subset of the timeline's entire history of events.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/views
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
Request Object

When this method runs, it passes in a request object that contains a stream_view object, as shown below:

▿ JSON Request

{
  "stream_view": {
    "name": "Acme Inc.'s member statement",
    "description": "Acme Inc.'s member statement, defined as a view on the user event timeline.",
    "query": "select * from table",
    "event_stream_stream_id": 1
}


This object is detailed in the following table:

Request Attributes for Stream View

Attribute Type
Required/Optional
Description
name string
required
Name of the timeline view. For example, "Acme Inc.'s member statement".
description string
optional
Description of timeline view. For example, "Acme Inc.'s member statement, defined as a view on the customer timeline".)
query string
optional
Timeline view query for building an SQL query, such as target_id, event_category_id, event_type_ids, since and count.
event_stream_stream_id integer
required
Identifier of the associated timeline.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_view object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "stream_view": {
    "id": 3,
    "name": "Acme Inc.'s member statement 1",
    "slug": "ACME_INCS_MEMBER_STATEMENT_1",
    "description": "Acme Inc.'s member statement, defined as a view on the user event stream.",
    "event_stream_stream_id": 14,
    "query": "target_id, event_category_id, event_type_ids, since, count"
  }
}


This object is detailed in the following table:

Response Attributes for Stream View

Attribute Type Description
id integer Identifier for the timeline view.
name string Name of the timeline view. For example, "Acme Inc.'s member statement".
slug string Permlink for the timeline view. For example, ACME_INCS_MEMBER_STATEMENT.
description string Description of timeline view. For example, "Acme Inc.'s member statement, defined as a view on the customer timeline".)
query string Timeline view query for filtering a timeline service's response. Filters for a timeline query need to match the timeline query.
event_stream_stream_id integer Identifier of the associated timeline.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_stream_view_found Specified timeline view cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Details on a Timeline View

Retrieve details of a timeline view. The details returned can be presented in a retrieved page of events from the timeline view.

This endpoint operates in the following steps:

  1. Fetch page of raw event data from timeline storage service.
  2. Fetch rendering templates for the view.
  3. Return rendered page of events.
Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/views/:view_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
timeline_id Identifier for an event timeline. Same as id on the stream object.
view_id Identifier for a timeline view.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_view object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "stream_view": {
    "id": 3,
    "name": "Acme Inc.'s member statement 1",
    "slug": "ACME_INCS_MEMBER_STATEMENT_1",
    "description": "Acme Inc.'s member statement, defined as a view on the user event stream.",
    "event_stream_stream_id": 14,
    "query": "target_id, event_category_id, event_type_ids, since, count"
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_stream_view_found Specified timeline view cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create an Event Template

Create an event template that is used for rendering events on a user's timeline.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/event_templates
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains a event_template object, as shown below:

▿ JSON Request

{
  "event_template": {
    "html":  "<p>{{mylist}}{{ item }}{{mylistTypo}}</p>",
    "plain_text": "plain text",
    "event_stream_event_type_id": 7
  }
}


This object is detailed in the following table:

Request Attributes for Event Template

Attribute Type
Required/Optional
Description
html string
optional
Value must be in valid HTML format and consistent with the Liquid templating language.
plain_text string
optional
Presentation of HTML in plain text.
event_stream_event_type_id integer
required
Event type associated with the timeline.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a event_template object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "event_template": {
    "id": 1,
    "event_stream_event_type_id": 7,
    "html": "<p>{{mylist}}{{ item }}{{mylistTypo}}</p>",
    "plain_text": "plain text"
  }
}


This object is detailed in the table below:

Response Attributes for Event Template

Attribute Type Description
id integer Database identifier for the event template.
event_stream_event_type_id integer Identifier of the associated timeline event type.
html string Value must be in valid HTML format and consistent with the Liquid templating language.
plain_text string Presentation of HTML in plain text.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
validation Mustache template in HTML is not valid. Please check it again.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Rendering Context

Create a rendering context, which determines how an event should be rendered in a given context. The rendering context model is a global list of contexts in which to render events. It targets a template to a type of environment in which to render.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/timelines/rendering_contexts
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains a rendering_context object, as shown below:

▿ JSON Request

{
  "rendering_context": {
     "name": "mmc:customer:campaigns",
     "description": "rendering context description"
   }
}


This object is detailed in the following table:

Request Attributes for Rendering Context

Attribute Type
Required/Optional
Description
name string
required
Name of the rendering context.
description string
optional
Description of rendering context.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_context object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "rendering_context": {
    "id": 1,
    "name": "mmc:customer:campaigns",
    "slug": "MMC_CUSTOMER_CAMPAIGNS",
    "description": "description",
    "organization_id": 4982
  }
}


This object is detailed in the following table:

Response Attributes for Rendering Context

Attribute Type Description
id integer Database identifier for the rendering context.
name string Name of the rendering context.
slug string Permalink identifier for the rendering context.
description string Description of the rendering context.
organization_id integer Identifier for organization utilizing the rendering context.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code and a string that can be either ok or error. When the string returned is ok, the transaction processed successfully. When the string returned is error, you need to determine what error occurred. For more information, see Generic Statuses and Errors.

SMS Validation API

The SMS Validation API uses a verification object to send Short Message Service (SMS) messages to customers as a link to follow or as an activation code to apply. A link redirects the customer to the rewards page. An SMS activation code enables a customer to redeem points (or other loyalty currency) for rewards via the Rewards Store API.

For development and testing purposes, this API support resetting a specific customer or all customers who have verified with a given phone number. With this API, you can clear a customer or a phone number of all SMS verifications.

This API has the following methods:

Sends an SMS message that contains an activation code or link to a customer.

Endpoints

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/verifications/sms
POST /priv/v1/apps/:api_key/external/users/:external_id/verifications/sms

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform. Necessary to authenticate any HTTP request to a SessionM API. The key is associated with an API secret, which ties the authentication to a specific application or web site within the organization. The SessionM Platform maintains each application or site as a digital property, which can be configured using the SessionM UI.
user_id Internal identifier for the customer in the SessionM Platform.
external_id Identifier for a customer in an external system that integrates with the SessionM Platform.

Request Object

This method supplies the user request object shown below:

▿ JSON Request

{
  "user": {
    "phone": "555-678-9000",
    "message": "Welcome to [company] Rewards! Here is your activation code: {code}"
  }
}


Request Attributes for User

Attribute Type
Required/Optional
Description
phone string
required
Customer phone number. US/CA numbers with country code of 1 supported. Supplied phone numbers must have 10 digits (3-digit area code and 7-digit phone number). Do not include a country code. Data is encrypted for storage on the disk. Properly formatted examples of phone numbers include:
5556789000
(555)-678-9000
555-678-9000
(555) 678 9000
555 678 9000
message string
required
SMS message sent to the customer. You set the message content, but it must include {code}. For example, "Welcome to SessionM! Here is your activation code: "{code}".

Response Object

This method returns the verification request object shown below:

▿ JSON Response

{
  "status": "ok",
  "verification": {
      "id": 11111111,
      "status": "pending",
      "mode": "sms"
  }
}


Response Attributes for Verification

Attribute Type Description
id integer Customer verification identification number.
status string Verification status:
pending - SMS message sent; waiting for further activity.
valid - SMS message sent and verification code submitted correctly; account now verified.
expired - SMS message sent but no action taken in the allotted time. Code now expired; need to request another SMS message with new activation code.
invalid - An error occurred during handling request.
mode string Set to sms.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code and a string that can be either ok or error. When the string returned is ok, the transaction processed successfully. When the string returned is error, you need to determine what error occurred.

Returned errors can be either method-specific or generic. This method has the following method-specific errors:

Code Returned String Reason
sms_limit_reached Reached SMS Limit. Contact Customer Support. Provided phone number has reached its daily limit for SMS messages.
sms_invalid_number Invalid Number Provided phone number is not a valid U.S. number.
sms_invalid_device Invalid Device Provided phone number is not associated with a supported device. Only phone numbers for mobile devices are accepted.
sms_not_supported SMS not supported for this number An improper number was supplied and the request failed. Number not in the US or device is not a mobile device. (For example, a pager or landline device.)
sms_service_down Service is down Phone verification service is down.
sms_already_verified NA Customer trying to re-verify after already verifying.
sms_link_expired NA Customer must act within timeframe; if they do not, the code or link expires and Cannot be used.
sms_invalid_code NA Customer specified wrong code or followed wrong URL.
NA Reached Identification Limit Customer has exceeded the maximum number of SMS requests allowed.
NA Reached Max Number of Verifications. Contact customer support. Phone number has exceeded the maximum number of allowed verifications (phone number is already verified and in use).
NA Missing Phone Number No phone number was supplied in the request.

For information on the generic statuses and errors returned for any object, see Generic Statuses and Errors.

Verify a Customer Activation Code

Sends an SMS message that verifies a customer's activation code.

Endpoints

▿ REST Endpoints

With Verification ID:
POST /priv/v1/apps/:api_key/users/:user_id/verifications/sms/:verification_id
POST /priv/v1/apps/:api_key/external/users/:external_id/verifications/sms/:verification_id

Without Verification ID:
POST /priv/v1/apps/:api_key/users/:user_id/verifications/sms/verifycode
POST /priv/v1/apps/:api_key/external/users/:external_id/verifications/sms/verifycode

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform. Authenticates any HTTP request to a SessionM API. The key is associated with an API secret, which ties the authentication to a specific application or web site within the organization. The SessionM Platform maintains each application or site as a digital property, which can be configured using the SessionM UI.
user_id Internal identifier for the customer in the SessionM Platform.
external_id Identifier for a customer in an external system that integrates with the SessionM Platform.
verification_id Customer verification identification number.

Request Object

This method passes the verification request object shown below:

▿ JSON Request

{
  "verification": {
    "code": "123456"
  }
}


Request Attributes for Verification

Attribute Type
Required/Optional
Description
code string
required
Verification code submitted by customer.

Response Object

The response object contains a status key-value pair and a verification object, as shown below:

▿ JSON Response

{
  "status": "ok",
   "verification": {
      "id": 11111111,
      "status": "valid",
      "mode": "sms"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code and a string that can be either ok or error. When the string returned is ok, the transaction processed successfully. When the string returned is error, you need to determine what error occurred. ßFor more information, see Generic Statuses and Errors.

Retrieve an SMS Status

Retrieves an SMS status for a specified customer.

Endpoints

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/verifications/sms
GET /priv/v1/apps/:api_key/external/users/:external_id/verifications/sms

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a verification object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "verification": {
      "id": 11111111,
      "status": ["pending","valid","expired","invalid"],
      "mode": "sms"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Reset an SMS Status

Resets a new SMS status for a specified customer.

Endpoints

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/verifications/reset
POST /priv/v1/apps/:api_key/external/users/:external_id/verifications/reset
POST /api/v1/apps/:api_key/verifications/reset?auth_token=xxxxx

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token Authorization token for resetting an SMS status. For example: auth_token=36898*.

Request Object

Not applicable.

Response Object

Only status is returned, as shown below:

▿ JSON Response

{
  "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found SMS status cannot be reset because customer was not found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Reset SMS Status for a Phone Number

Searches for every customer that has used the specified phone number and deletes the associated customer verification record. Doing so allows a phone number to be reused.

Endpoints

▿ REST Endpoints

POST /priv/v1/apps/:api_key/verifications/reset/number

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

When this method runs, it passes in a request object that contains a user object containing a phone key-value pair, as shown below:

▿ JSON Request

{
  "user": {
    "phone": "555-678-9000"
  }
}


US/CA numbers with a country code of 1 are supported. All supplied numbers must consist of only 10 digits (area code plus the phone number); this excludes the country code.

Formatted examples of phone include:

Response Object

Only status is returned, as shown below:

▿ JSON Response

{
  "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data No phone number supplied.
user_not_found SMS status cannot be reset because customer was not found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Data Privacy API

The Data Privacy API provides functions for creating and maintaining requests on behalf of customers to forget or export privacy data. In addition, the API can be used to create requests that restrict or reinstate a customer's access to loyalty or marketing programs. These data privacy features are available to all clients committed to fulfilling customer requests seeking to safeguard or review their own personal data.

This API provides the following methods:

Retrieve All Privacy Requests

Gets all data privacy requests initiated by all platform users on behalf of customers.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/privacy
GET /priv/v1/apps/:api_key/external/users/:external_id/privacy

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a privacy_response array, populated with one or more privacy requests, as shown below:

▿ JSON Response

{
    status: ok,
    privacy_requests:
    [
        {
            "user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
            "status": "completed",
            "report_url": "https://www.acme.com/gdpr_user_data/gdpr_all_reports_20180531_e5425484-3db4-11e8-83c2-064689b47c37.zip?AWSAccessKeyId=ASIAIWCEQS7JVVII5PMQ&Expires=1528041863&Signature=a5rDYLPKwYkqFDFXQfVFf%2B1PcP8%3D&x-amz-security-token=FQoDYXdzEDEaDH42wWSqUyFg1OLPFCLqAU8K%2BWPQd%2BKP9ZPpy5M9YlcOhPSVY%2FAy%2BX4h%2BDLyQYu6HzeoAGKvl0motl42FggSNbUPkKAO2LBD853LoaN6Fwkxpi%2BmO0be316QZCeGSU2CH5cwfGVipKJ802PsPZnZ3pprhjCeNYRkY9w3umXaGZFVV6JV7pwsw3P50Q6WDqCyNYtviZB4FA3ZNxTwa5WzWfyA8FlG1QXzMATJkHKRetgpD65JSuuhDSZ9RGmjbIxMKY%2FsWsrN%2BRHnmMEbPDs%2FfWzk%2BZt9onGIR9IPKDXeHXBIBbr8AtCWWnVXhS4GVGurkIPRjy%2FgBpqqxCis2MXYBQ%3D%3D",
            "export_data_status": "completed"
        }
    ]
}


This object is documented in the following table:

Response Attributes for Privacy

Attribute Type Description
user_id string Internal identifier for the customer within the SessionM Platform.
status string Status of any privacy request. Possible values include: completed and in_progress.
report_url string URL for the report detailing privacy requests. Passed as a parameter only if privacy request has type.
export_data_status string Status of job being run to export data for a customer. Possible values include: completed, report_url_expired, and in_progress. Passed as a parameter only if privacy request has type.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Keep in mind the following error conditions:

For more information on generic errors, see the associated section in Generic Statuses and Errors.

Create Request to Forget Privacy Data

Creates request to forget any customer information, such as an email address or a physical address as well as any loyalty data about available offers and earned achievements. Once implemented, the customer account and all associated data is removed from any loyalty or marketing programs.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/privacy/forget
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/forget

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

The response object contains only a status key-value pair as shown below:

▿ JSON Response

{
    "status": "ok"
}

Statuses and Error

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Keep in mind the following error conditions:

For more information on generic errors, see the associated section in Generic Statuses and Errors.

Create Request to Export Privacy Data

Creates an export data request, which returns a CSV file of the customer’s data that can be downloaded and sent to the customer. The exported CSV files contain data from a customer profile as well as any data derived from calculated metrics, purchases, marketing and loyalty program-related events, and application sessions.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/privacy/export
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/export

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a message string, which indicates that the export is being processed and is shown below:

▿ JSON Response

{
    "status": "ok",
    "message": “Export Job is now processing”
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Keep in mind the following error conditions:

For more information on generic errors, see the associated section in Generic Statuses and Errors.

Retrieve All Requests to Export Privacy Data

Gets all data requests initiated by all platform users to export privacy data.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/privacy/export
GET /priv/v1/apps/:api_key/external/users/:external_id/privacy/export

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a gdpr_user_data array, populated with one or more export requests, as shown below:

▿ JSON Response

{
    "status": "ok",
    "gdpr_user_data": [
    {
        "user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
        "report_url": "https://www.acme.com/gdpr_user_data/gdpr_all_reports_20180531_e5425484-3db4-11e8-83c2-064689b47c37.zip?AWSAccessKeyId=ASIAIWCEQS7JVVII5PMQ&Expires=1528041863&Signature=a5rDYLPKwYkqFDFXQfVFf%2B1PcP8%3D&x-amz-security-token=FQoDYXdzEDEaDH42wWSqUyFg1OLPFCLqAU8K%2BWPQd%2BKP9ZPpy5M9YlcOhPSVY%2FAy%2BX4h%2BDLyQYu6HzeoAGKvl0motl42FggSNbUPkKAO2LBD853LoaN6Fwkxpi%2BmO0be316QZCeGSU2CH5cwfGVipKJ802PsPZnZ3pprhjCeNYRkY9w3umXaGZFVV6JV7pwsw3P50Q6WDqCyNYtviZB4FA3ZNxTwa5WzWfyA8FlG1QXzMATJkHKRetgpD65JSuuhDSZ9RGmjbIxMKY%2FsWsrN%2BRHnmMEbPDs%2FfWzk%2BZt9onGIR9IPKDXeHXBIBbr8AtCWWnVXhS4GVGurkIPRjy%2FgBpqqxCis2MXYBQ%3D%3D",
        "export_data_status": "completed"
    }
    ]
}


This object is documented in the following table:

Response Attributes for GDPR User Data

Attribute Type Description
user_id string Internal identifier for the customer within the SessionM Platform.
report_url string URL for the report detailing exported data. Passed as a parameter only if privacy request has type.
export_data_status string Status of job being run to export data for a customer. Possible values include: completed, report_url_expired, and in_progress. Passed as a parameter only if privacy request has type.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Keep in mind the following error conditions:

For more information on generic errors, see the associated section in Generic Statuses and Errors.

Create Request to Restrict or Reinstate Customer

Creates a request that toggles a user between a status of "Restrict" and "Reinstate". Restricting a customer removes their ability to log in and ensures that they or anyone else cannot access any personal information. It's important to note that the data is NOT removed; only access to the data is temporarily paused. Reinstating a customer re-establishes their ability to log in and ensures that access to personal data is restored.

If a restrict request is in progress, the reinstate route will not work and visa versa.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/privacy/restrict
POST /priv/v1/apps/:api_key/external/users/:external_id/privacy/restrict

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

The response object contains only a status key-value pair as shown below:

▿ JSON Response

{
    "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Keep in mind the following error conditions:

For more information on generic errors, see the associated section in Generic Statuses and Errors.

Audiences

This grouping presently includes the Tags API for supporting the classification of customers with audience segmentation tags.

Tags API

Tags objects manage arbitrary strings that can be attached to a customer profile. They act as keyword classifiers and are associated with a counter to indicate the number of times a tag has been assigned.

Tags allow you to define segments of customers, each of which can be associated with targeting rules. Typically, the rules are designed to test for the presence of tags or their values and then take conditional steps based on them. For example, they can track simple customer actions such as abandoning an online shopping cart. With knowledge of the customer's decision to abandon a cart, you can retarget the customer to a new campaign or outcome.

In addition, tags may also have a TTL (Time to Live) associated with them. These tags expire and disappear after the TTL expires. Note that a tag may have either a count (counter tag) or a TTL (expiring tag), but not both.

This API provides a means to attach tags to a customer, show the tags that are already attached, or delete them. It provides the following methods:

Create or Increment a Customer Tag

Specifies a counter tag if it does not exist and sets its count to 1. If the counter tag already exists, its count is incremented by one.

If a TTL is specified, an expiring tag is created instead and the tag is set to the value specified. This kind of tag does not have a count. Note that multiple tags may be specified in a single invocation.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/tags
POST /priv/v1/apps/:api_key/external/users/:external_id/tags

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains the tags object, as shown below:

▿ JSON Request

{
   "tags":[
    "tag1",
    "tag2"
   ],
   "ttl":2592000
}


This object is detailed in the following table:

Request Attributes for Tags

Attribute Type
Required/Optional
Description
tags array string
required
Tags to create.
ttl integer
optional
Time to Live, in seconds. If provided, attribute specifies number of seconds that tag remains set after created or updated. After specified time, tag expires.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:

▿ JSON Response

{
   "status":"ok",
   "tags":{
    "tag1":2,
    "tag2":5,
    "tag3":0
   }
}


This object is detailed in the following table:

Response Attributes for Tags

Attribute Type Description
tags dictionary string: integer All of customer's tags and their counts.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Customer Tags

Retrieves all the tags associated with a customer, along with their counts.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/tags
GET /priv/v1/apps/:api_key/external/users/:external_id/tags

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:

▿ JSON Response

{
   "status":"ok",
   "tags":{
    "tag1":2,
    "tag2":5,
    "tag3":0
   }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Batch Job to Ingest Tags from a CSV File

Generates a collection of tags by ingesting them from a CSV file. This approach allows the caller to avoid supporting real-time submissions that create tags. In this case, the API allows a client to submit tags via a batch.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST    /priv/v1/apps/:api_key/batch/tags

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

When this method runs, it passes in a tags request object that utilizes information in a CSV file. Consider the following samples:

▿ JSON Request

{
  "tags":{
    "request_id":"917",
    "url":"https://mybucket.s3.aws.acme.com/tags_contexts-20140101.csv",
    "md5":"acbd18db4cc2f85cedef654fccc4a4d8",
    "notify":"https://test.com/sessionm/tags/job/notification?id=JOB_ID&status=JOB_STATUS&request_id=JOB_REQUEST_ID"
  }
}

CSV File Corresponding with Request

external_id,tag,expires
user1234,foo,
user1235,bar,
user1236,bar,1 day
user1237,foo,


While the value for the attributes will differ, the tags request object contains the same attributes as those offered for an events request object.

The tags object ingests events headers and data from an associated CSV file, which is detailed below:

CSV Headers

Attribute Type
Required/Optional
Description
user_id string
required, unless external_id provided; when both are present, user_id takes precedence.
CSV header for a customer ID.
external_id string
required, unless user_id provided; when both are present, user_id takes precedence.
CSV header for an external customer ID.
tag string
required
CSV header for the tag.
expires string
optional
CSV header for the the tag's TTL (Time to Live).

Response Object

In addition to a status key-value pair, the response object contains a tags object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "tags":
    {
      "id": 7,
      "request_id": "sample_id_1",
      "status": "created"
    }
}


The attributes for this object are identical to those offered for an events response object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Delete a Customer Tag

ENTIRE SECTION NEEDS REVIEW

Deletes a customer tag.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/users/:user_id/tags
DELETE /priv/v1/apps/:api_key/external/users/:external_id/tags

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains the tags object, as shown below:

▿ JSON Request

{
  "tags":[
      "Tag1",
      "Tag2",
      "Tag3"
  ]
}


This object is detailed in the following table:

Request Attributes for Tags

Attribute Type
Required/Optional
Description
tags array string
required
Tags to delete.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:

▿ JSON Response

{
   "status":"ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Campaigns

The APIs in this grouping serve scheduled and targeted customer engagement of any kind, including promotions, display advertising, personalized push notifications or in-app messaging. APIs exist for the following:

Campaigns API

Campaign objects represent scheduled and targeted customer engagements of any kind: messaging, promotions, games and display advertising.

Using the SessionM Administration Portal, you can create campaigns and configure their associated customer actions and outcomes. At the same time, campaigns allow you to collect data and analyze campaign effectiveness. With that data, you can trigger additional marketing activities as well as target future campaigns. Campaigns can target specific audience segments, as well as support a set of rules around campaign duration, opt-in requirements, delivery methods, creative assets and desired customer actions.

The platform supports a number of campaign types, including:

Campaign objects provide SessionM partners with the ability to query campaigns targeted to a specific customer and fetch customer-specific state information related to campaigns. In addition, some of the methods retrieve a campaign along with its data and then validate a customer’s eligibility for the specified campaign.

This API provides the following methods:

Retrieve All Campaigns for a Specified Customer

Retrieves all of the campaigns associated with a specified or authorization token. Note that the endpoints that utilize a user_id or external_id are available for registered customers (users); however, GET /api/v1/apps/:api_key/campaigns?auth_token=xxxxx applies to unregistered, anonymous customers.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints (Retrieve All Campaigns for a Specified Customer)

GET /priv/v1/apps/:api_key/users/:user_id/campaigns
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns
GET /api/v1/apps/:api_key/campaigns?auth_token=xxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token Specifies authorization token for operation. For example: auth_token=4296.
offers Boolean that returns offer data associated with an active campaign. For example, offers=true. Note that this boolean supports campaigns created on the SessionM Platform as a "Participation Challenge."

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaigns object, which contains tiles and promotions arrays shown below:

▿ JSON Response (Retrieve All Campaigns for a Single Customer)

{
    "status": "ok",
    "campaigns": {
        "tiles": [
            {
                "campaign_id": 1255,
                "name": "promotionCampaign",
                "group_id": 2917,
                "creative_id": 2983,
                "start_date": "2017-07-03 19:04:18",
                "end_date": "2017-08-03 19:04:18",
                "opt_in_starts_at": "2017-07-03 19:04:18",
                "opt_in_ends_at": "2017-08-03 19:04:18",
                "permalink": "6a04f24c-6022-11e7-8c24-3bcbbae62f9c",
                "template": {
                    "type": "internal_tile",
                    "message": {
                        "points": 0
                    },
                    "action": {
                        "tracking_urls": [
                            "https://api-qa4.q-sessionm.com/api/v1/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/creatives/2983/stats/3726c65e-7de4-11e7-959f-f9d291045c00/seen/track?auth_token=v2--Ga0yJV7TyMJsIjOZ40MitXJQanHlX_SrG3IZl-TmYXY=--QyLCZ-H6d08Ny9dzS_xavtjKjOMT2HznmZz8nfGcOm3NXKduOSzkkJpZ4bgoPKjQsA==&xsid=48792ee2-0e5e-11e7-8716-9311a9d25bb0&locale=en-us"
                        ],
                        "event_meta_data": {
                            "ad_unit_id": 2983,
                            "ad_stat_id": "3726c65e-7de4-11e7-959f-f9d291045c00"
                        }
                    }
                },
                "progress": {
                    "state": "completed"
                },
                "behaviors": {},
                "version": 2,
                ""
            }
        ],
        "promotions": [
            {
                "campaign_id": 1064,
                "name": "Launch 2",
                "group_id": 2578,
                "creative_id": 2640,
                "start_date": "2017-06-15 18:35:37",
                "end_date": "2017-07-15 18:35:37",
                "opt_in_starts_at": "2017-06-15 18:35:37",
                "opt_in_ends_at": "2017-07-15 18:35:37",
                "permalink": "6ce11f7c-51f9-11e7-822a-02d3bae62f9c",
                "template": {
                    "type": "internal_full_page",
                    "html_payload": "https://api-qa4.q-sessionm.com/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/users/48792ee2-0e5e-11e7-8716-93115045e6c0/ads/2640"
                },
                "progress": {
                    "state": "completed"
                },
                "behaviors": {},
                "version": 2
            },
            {
                "campaign_id": 1443,
                "name": "TEstt0714441",
                "group_id": 3232,
                "creative_id": 3364,
                "start_date": "2017-07-14 20:37:16",
                "end_date": "2017-08-14 20:37:16",
                "opt_in_starts_at": "2017-07-14 20:37:16",
                "opt_in_ends_at": "2017-08-14 20:37:16",
                "permalink": "3964b522-68d4-11e7-8479-4fdfbae62f9c",
                "template": {
                    "type": "internal_full_page",
                    "html_payload": "https://api-qa4.q-sessionm.com/apps/70261ce1e55ee3a5c282d48bdd4fa343230c04e0/users/48792ee2-0e5e-11e7-8716-93115045e6c0/ads/3364"
                },
                "progress": {
                    "state": "in_progress",
                    "behaviors": [
                        {
                            "behavior_id": 1444,
                            "event_name": "3dac9302-68d4-11e7-9412-9e32bae62f9c",
                            "name": "TEstt0714441 Campaign Action 1",
                            "progress": 0,
                            "goal": 1
                        }
                    ]
                },
                "behaviors": {
                    "t_estt0714441 campaign action 1": {
                        "type": "composite",
                        "points": 0,
                        "achieved": 4,
                        "max_times_repeatable": null,
                        "max_times_repeatable_per_period": null,
                        "period": 7776000,
                        "min_time_between_events": null,
                        "consecutive": false,
                        "goals": {
                            "campaigns.1443.loaded": {
                                "type": "goal",
                                "points": 4,
                                "completed": false,
                                "required": true,
                                "earn_count": 1,
                                "group_id": "0",
                                "progress": {
                                    "event_name": "campaigns.1443.loaded",
                                    "type": "count",
                                    "points": 4,
                                    "max_times_repeatable": null,
                                    "max_times_repeatable_per_period": null,
                                    "period": 7776000,
                                    "min_time_between_events": null,
                                    "consecutive": false,
                                    "achieved": 4,
                                    "current_count": 0,
                                    "total_count": 1
                                }
                            }
                        },
                        "groups": {
                            "0": {
                                "type": "group",
                                "current_count": 0,
                                "total_count": 1,
                                "num_goals": 1,
                                "completed": false
                            }
                        }
                    }
                },
                "version": 2
            }
        ]
    }
}


The attributes for each are identical and are covered in a combined section below.

Tiles and Promotions Array

The following table provides details on the tiles and promotions arrays, which can contain multiple campaigns:

Response Attributes for Campaigns in a Tiles and Promotions Arrays

Attribute Type Description
campaign_id integer Campaign identifier internal to SessionM.
name string Campaign name.
group_id integer Internal ad group identifier.
creative_id integer Platform-generated ID of the ad unit content, which is also called creative content.
start_date string Campaign starting date.
end_date string Campaign end date.
opt_in_starts_at string Opt-in starting date.
opt_in_ends_at string Opt-in ending date.
permalink string Campaign permalink.
template object See the Template Object section.
progress object Contains customer's current status for this campaign. For more information, see Progress Object.
behaviors object See the Behaviors Object section.
version string Campaign version.
Template Object

The following table provides details on the template object:

Response Attributes for Template

Attribute Type Description
type string Campaigns API returns campaigns that have ad unit with ad type set to one of the following: "internal_tile", "internal_full_page" or "internal_behavior".
message object Returned only when the type equals "internal_tile". Contains configuration of the tile setup: header, sub-header, description, icon_url, app_icon_alt_text, image_url, image_alt_text, call_to_action, points, layout and video_url.
html_payload string The ad unit URL for the given customer.
action object See the Action Object section below.
Action Object

The following table provides details on the action object:

Response Attributes for Action

Attribute Type Description
type string Type of action. Options include: "open_ad", "deep_link", "external_link", "campaign".
url string Next ad URL if creative click tracking is disabled OR user session has been initialized with SessionM SDK. Otherwise the action tracking URL is used.
tracking_urls array of strings Array of URLs used to track an action associated with a tile template.
section string Campaign section from ad unit events.
campaign_id integer Primary key of the ad campaign for the ad unit.
event_meta_data object Metadata about the event, including an integer, ad_unit_id, which is the identifier for the ad unit, and a string, ad_stat_id, which is the identifier for the ad stat.
Behaviors Array

The following table provides details on the behaviors array:

Response Attributes for Behaviors Array

Attribute Type Description
behavior_id integer Internal SessionM ID for the behavior.
event_name string Name of the event that triggers behavior when submitted to Events API.
goal integer Number of events customer must perform to complete behavior.
name string External name of behavior.
progress integer Number of times customer has completed behavior.
Behaviors Object

The following table provides details on the behaviors object:

Response Attributes for Behaviors Object

Attribute Type Description
type string Behavior type: "unique", "composite", "count".
points integer Number of points associated with behavior.
achieved integer Number of times behavior was achieved.
max_times_repeatable integer Maximum number of times behavior can be repeated.
max_times_repeatable_per_period integer Maximum number of times behavior can be repeated in a specified period.
period integer Period of time in which behavior can be performed. Configurable unit of measure.
min_time_between_events integer Min time period between events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds.
consecutive boolean Indicator whether events need to happen on consecutive days.
goals object See the Goals Object section below.
groups object See the Groups Object section.
Goals Object

The following table provides details on the goals object:

Response Attributes for Goals Object

Attribute Type Description
type string Type for this object is "goal".
points integer Points associated with goal.
completed boolean Specifies whether goal was or wasn't completed.
required boolean Specifies whether goal is or isn't required.
earn_count integer Customer action (sometimes referred to as a goal) count required to complete the composite action.
group_id string Identifier for group.
progress object See the Progress Object section below.
Progress Object

The following table provides details on the progress object:

Response Attributes for Progress Object

Attribute Type Description
event_name string Name of associated event.
type string Behavior type: "unique", "composite", "count".
points integer Number of points associated with behavior.
max_times_repeatable integer Maximum number of times behavior can be repeated.
max_times_repeatable_per_period integer Maximum number of times behavior can be repeated in a specified period.
period integer Period of time in which behavior can be performed. Configurable unit of measure.
min_time_between_events integer Min time period between events. For example, 1 day, 1 week, 1 month, 90 days. Specify value in seconds.
consecutive boolean Indicator whether events need to happen on consecutive days.
achieved integer Number of times behavior was achieved.
current_count integer Event occurrences count.
total_count integer Required event count.
Groups Object

The following table provides details on the groups object:

Response Attributes for Groups Object

Attribute Type Description
type string Object type is "group".
current_count integer Count of completed goals in the group.
total_count integer Goal count required to complete the group.
num_goals integer Goal count in the group.
completed boolean Specifies whether the goal group been completed.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
No_active_campaign_found No campaign was found for the specified ID.
User_not_found No customer was found for the specified ID.
Invalid_api_key No application was found for the given key.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Customer Status for a Campaign

Opts a customer into a campaign for which they are eligible. This transaction updates their status and make them able to earn the incentive associated with this campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:campaign_id/opt_in
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:campaign_id/opt_in

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customers within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
campaign_id Campaign identifier internal to SessionM.

Request Object

Not applicable.

Response Object

Since this method's response object is identical to what is returned for the method that returns all campaigns, see the "Response Object" section in Retrieve All Campaigns for a Customer for more information.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_ineligible_for_campaign Customer is ineligible for specified campaign.
opt_in_not_started Opt in has not started.
opt_in_ended Opt in has ended.
opt_in_limit_reached User limit reached.
opt_in_error Opt in failed for unknown reason.

Note that all of the above errors apply only when a customer has opted in to a campaign.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Information for a Campaign

Retrieves basic information for a campaign without having to provide any user-specific data; it does not pass a user ID parameter in the endpoint. Individual campaigns can be specified using either the ad_campaign_id or permalink parameters. If you want to retrieve offer data associated with a campaign created on the SessionM Platform as a "Participation Challenge," you must set the offers attribute to true in the endpoint.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/:api_version/apps/:api_key/campaigns/:ad_campaign_id/info
GET /priv/:api_version/apps/:api_key/external/campaigns/:permalink/info

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
ad_campaign_id Internal SessionM ad campaign ID.
permalink Campaign permalink that can be customer-defined or auto-generated.
offers Boolean that returns offer data associated with an active campaign. For example, offers=true. Note that this boolean supports campaigns created on the SessionM Platform as a "Participation Challenge."

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, as shown below:

▿ JSON Response (Retrieve Campaign and Associated Offer Information without Specifying User ID)

{
  "status": "ok",
  "campaign": {
    "campaign_id": 1,
    "permalink": "my_flock_to_unlock_campaign",
    "starts_at": "2017-05-09 17:36:48",
    "ends_at": "2017-05-13 17:36:48",
    "optin_required": true,
    "opt_in_starts_at": "2017-05-09 17:36:48",
    "opt_in_ends_at": "2017-05-13 17:36:48",
    "offers": [{
      "offer_id": 1,
      "name": "flock to unlock",
      "type": "outcome_entry",
      "total_entries": 2114,
      "outcomes": [{
        "outcome_id": 1,
        "threshold": 1000,
        "entries": 1000,
        "completed": true,
        "type": "tag",
        "data":
        {
          "name": "my_sample_promotion_1"
        }
    }]
  }]
}


This object is detailed in the following tables:

Response Attributes for Campaign

Attribute Type Description
campaign_id integer Campaign identifier internal to SessionM.
permalink string Campaign permalink that can be customer-defined or auto-generated.
optin_required boolean Indicates whether or not opt-in is required for customers wanting to participate in campaign. true if an opt-in is required; false if it is not.
starts_at string Campaign start date.
ends_at string Campaign end date.
opt_in_starts_at string Opt-in starting date.
opt_in_ends_at string Opt-in ending date.
offers array Array of offer objects. For more information, see the Offers table below.

Response Attributes for Offers

Attribute Type Description
offer_id integer Identifier for reward (offer) tied to campaign.
name string Name of the reward (offer).
type string Set to outcome_entry, this attribute indicates offer has outcomes.
total_entries integer Total count of outcome entries. reflects entry count in entries table.
outcomes array Array of outcome objects. For more information, see table below.

Note: Offers can also be returned from the Campaigns API in an array, campaign.offers: [].

Response Attributes for Outcomes

Attribute Type Description
outcome_id integer Identifier for outcome of reward (offer) tied to campaign.
threshold integer Action count that triggers outcome.
entries integer Action count that includes logic for cumulative outcomes.
completed boolean Indicates if threshold has been reached.
type string Type of outcome.
data object Data associated with outcome. Can contain points (integer for points outcome), name (string for tag name defined for outcome) or payload (free form data associated with outcome).

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
No_active_campaign_found No campaign was found for the specified ID.
User_not_found No customer was found for the specified ID.
Invalid_api_key No application was found for the given key.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Customer Progress for a Campaign

Retrieves a customer's progress for a specified campaign, even after the campaign ends. Responses display the customer’s state in the campaign and the progress they've made engaging in a behavior. For a more comprehensive view of a campaign, see Retrieve Information for a Campaign.

Note that individual campaigns can be specified using either the ad_campaign_id or permalink parameters.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/progress
GET /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/progress
GET /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/progress
GET /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/progress
GET /api/v1/apps/:api_key/campaigns/:ad_campaign_id/progress?auth_token=
GET /api/v1/apps/:api_key/external/campaigns/:permalink/progress?auth_token=

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
ad_campaign_id Internal SessionM ad campaign ID.
permalink Campaign permalink that can be customer-defined or auto-generated.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, as shown in a few samples below:

▿ JSON Response

{
    "status": "ok",
    "campaign": {
        "state": "qualified",
        "behaviors": [
        {
              "behavior_id": 525,
              "event_name": "ada7af74-9710-11e7-8803-9bbc32d1fae9",
              "name": "my_campaign_event_name",
              "progress": 0,
              "goal": 1
        }
        ]
    }
}

▿ JSON Response (With Customer Opting In)

{
    "status": "ok",
    "campaign": {
        "opted_in": true,
        "state": "opted_in",
        "behaviors": [
            {
                "behavior_id": 543,
                "event_name": "bce50a3c-9c8c-11e7-832f-e29b32d1fae9",
                "name": "moose_sleep_b",
                "progress": 0,
                "goal": 1
            }
        ]
    }
}

▿ JSON Response (With Customer Opting Out)

{
    "status": "ok",
    "campaign": {
        "opted_in": false,
        "state": "opted_out",
        "behaviors": [
            {
                "behavior_id": 525,
                "event_name": "ada7af74-9710-11e7-8803-9bbc32d1fae9",
                "name": "pretty_llamas-b",
                "progress": 0,
                "goal": 1
            }
        ]
    }
}


This object is detailed in the following table:

Response Attributes for Campaign

Attribute Type Description
opted_in boolean Displays only if customer has specifically opted in or out of campaign. Values include: true/false.
state string State related to customer. Possible values include: qualified, not_qualified, opted_in, opted_out, in_progress and completed.
behaviors array List of behaviors belonging to campaign and customer's progress associated with behaviors. For more information, see Behaviors Array.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
no_campaign_found No campaign was found for the specified ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Redemptions API

The Redemptions API provides the ability to create and manage redemption orders, usually promoted as part of a campaign. It provides clients with a way to track how many times a customer has earned a reward for a specific campaign. Knowing this information allows them to issue their own rewards to the customers participating in their campaign. Often, these rewards are fulfilled externally to qualifying customers via a third party.

Redemption orders are generated when customers complete campaigns. For example, a campaign might be set up in the following way: Buy 3 ACME products and earn an ACME-themed blanket. When a customer accomplishes this, a redemption order is automatically created to track their completion of the campaign. This allows ACME to redeem this order and send the customer the blanket through their rewards distribution center.

Using the API, you can check whether a customer is eligible to claim a campaign's reward upon completing an action using the Redeemable route. Once eligibility has been assessed, the Redemptions route can be used to actually claim the achievement.

This API provides six methods for retrieving, creating, updating and deleting redemption data. They include GETs for retrieving data on redeemable and redeemed orders, POSTs for redeeming orders, PUTs for updating orders and DELETEs for resetting orders. SessionM supports these operations with endpoints that reflect two kinds of transactional characteristics: campaign identifiers that utilize external campaign permalinks or internal campaign IDs; and, customer identifiers which are based on internal user IDs, external user IDs or authorization tokens.

In short, each method offers the following kinds of routes:

Note that campaigns must be set up to have redemption offers. Using the SessionM Administration Portal, you can create campaigns and configure their associated customer actions and outcomes. For more information, see the “Campaigns Module” section of the SessionM Platform: Onboarding Guide.

This API provides the following methods:

Retrieve Counts for Redeemable Orders

Retrieves counts associated with all redeemable offers available to a customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redeemable
GET /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redeemable
GET /api/v1/apps/:api_key/external/campaigns/:permalink/redeemable?auth_token=xxxxxxxxx
GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:campaign_id/redeemable
GET /priv/v1/apps/:api_key/users/:external_id/campaigns/:campaign_id/redeemable
GET /api/v1/apps/:api_key/campaigns/:ad_campaign_id/redeemable?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
ad_campaign_id Identifier for campaign.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains two attributes and another object.

It begins with a status key-value pair that provides the status of the transaction. The next line in the response specifies the redeemable boolean, which indicates whether or not the associated offer is in fact redeemable or not.

The response object also contains the campaign object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redeemable": true,
  "campaign": {
      "id": 364,
      "permalink": "daily_tester",
      "redemption_stats": {
      "total_earned": 4,
      "total_redeemed": 0,
      "total_expired": 0
    }
  }
}


This object is detailed in the following table:

Response Attributes for Campaign

Attribute Type Description
id integer Campaign identifier.
permalink string Campaign permalink.
redemption_stats object See Redemption Stats table below.

The following table presents the attributes available with the redemption_stats object:

Response Attributes for Redemption Stats

Attribute Type Description
total_earned integer Number of times the customer has unlocked (earned) the achievement.
total_redeemed integer Number of times the customer has claimed the achievement after earning it.
total_expired integer Number of expired achievements.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
not_found The campaign with the specified ID does not exist.
no_active_campaign_found The campaign was found but is not live.
missing_configuration_data The campaign is missing configuration data, and a behavior is not tied to the campaign.
unredeemable Called the Redeem route when the redeemable attribute was false. For example, calling the Redeem route again, after receiving the JSON Response (Campaign Redeemed by User) sample shown in the right-hand pane.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a List of Redemption Orders

Retrieves a list of all redemption orders a customer has accrued for a campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions
GET /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redemptions
GET /api/v1/apps/:api_key/external/campaigns/:permalink/redemptions?auth_token=xxxxxxxxx
GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/redemptions
GET /priv/v1/apps/:api_key/users/:external_id/campaigns/:ad_campaign_id/redemptions
GET /api/v1/apps/:api_key/campaigns/:ad_campaign_id/redemptions?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
ad_campaign_id Identifier for campaign.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a redemptions array, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemptions": [
  {
      "id": 1621752,
      "expires_on":
      "2017-01-19T04:59:00Z",
      "status": "redeemed",
      "payload":
      {
          "test": true
      }
  },
  {
      "id": 1621753,
      "expires_on": "2017-01-19T04:59:00Z",
      "status": "available",
      "payload":
      {
          "test": true
      }
  },
  {
      "id": 1621754,
      "expires_on": "2017-01-19T04:59:00Z",
      "status": "available",
      "payload":
      {
          "test": true
      }
  },
  {
      "id": 1621880,
      "expires_on": "2017-01-19T04:59:00Z",
      "status": "available",
      "payload":
      {
          "test": true
      }
  }
  ]
}


Each object in the array contains the attributes shown in the following table:

Response Attributes for Redemptions Array

Attribute Type Description
id integer Campaign identifier.
expires_on datetime Datetime at which reward associated with redemption order expires.
status string Status of redemption order. Can be: available, expired or redeemed.
payload object Additional data inherited from the redemption order's associated offer. Appears in the redemption object only when specified in the offer itself. Data reflects whatever attributes are configured in the offer; in this case a boolean called test.

Statuses and Errors

For information, see Statuses and Errors.

Retrieve a Specific Redeemed Order

Retrieves a specific order redeemed by a customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions/:id
GET /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redemptions/:user
GET /api/v1/apps/:api_key/external/campaigns/:permalink/redemptions/:user?auth_token=xxxxxxxxx
GET /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/redemptions/:user
GET /priv/v1/apps/:api_key/users/:external_id/campaigns/:ad_campaign_id/redemptions/:id
GET /api/v1/apps/:api_key/campaigns/:ad_campaign_id/redemptions/:id?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
ad_campaign_id Identifier for campaign.
id Identifier for a specific redeemed order.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a redemption object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemption": {
     "id": 1621752,
     "expires_on": "2017-01-19T04:59:00Z",
     "status": "redeemed",
     "payload": {
        "test": true
     }
  }
}

Statuses and Errors

For information, see Statuses and Errors.

Redeem the First Available Redemption Order

Redeems the first available redemption order, changing status to redeemed.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions
POST /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redemptions
POST /api/v1/apps/:api_key/external/campaigns/:permalink/redemptions?auth_token=xxxxxxxxx
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:ad_campaign_id/redemptions
POST /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:ad_campaign_id/redemptions/
POST /api/v1/apps/:api_key/external/campaigns/:ad_campaign_id/redemptions/?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
ad_campaign_id Identifier for campaign.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a redemption object with data, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemption":
  {
    "id": 27,
    "expires_on": "2017-07-14T03:59:00Z",
    "status": "available",
    "data": {
      "location": "vending_machine"},
    "payload":
    {
      "test": true
    }
  }
}


This object is detailed in the following table:

Response Attributes for Redemption with Data and Payload

Attribute Type Description
id integer Campaign identifier.
expires_on datetime
status string Status of redemption order. Can be: available, expired or redeemed.
data object Data that the client wants to associate with a redemption order via the POST or PUT route. Appears in the redemption object only when specified. Data reflects whatever attributes are configured in the redemption order; in this case, a string called location which specifies the location at which a redemption order was redeemed.
payload object Additional data inherited from the redemption order's associated offer. Appears in the redemption object only when specified in the offer itself. Data reflects whatever attributes are configured in the offer; in this case a boolean called test.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found The user (customer) not found.
no_campaign_found The campaign was not found.
not_found Invalid redemption ID for user (customer).
unredeemable Order is not redeemable.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Redeem a Specific Redemption Order

Redeems a specified redemption order, changing status to redeemed.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST
priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/redemptions/:id
POST
priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions/:id
POST
priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/redemptions/:id
POST
priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/redemptions/:id
POST
api/v1/apps/:api_key/campaigns/:ad_campaign_id/redemptions/:id?auth_token=
POST
api/v1/apps/:api_key/external/campaigns/:permalink/redemptions/:id?auth_token=

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
ad_campaign_id Identifier for ad campaign.
id Identifier for order.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a redemption object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemption": {
     "id": 1621755,
     "expires_on": "2017-01-19T04:59:00Z",
     "status": "redeemed",
     "payload": {
        "test": true
     }
  }
}

Statuses and Errors

For information, see Statuses and Errors.

Update a Redemption Order

Updates a specific redemption order.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redemptions/:id
PUT /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions/:id
PUT /api/v1/apps/:api_key/external/campaigns/:permalink/redemptions/:id?auth_token=xxxxxxxxx
PUT /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:campaign_id/redemptions/:id
PUT /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:campaign_id/redemptions//:id
PUT /api/v1/apps/:api_key/external/campaigns/:campaign_id/redemptions/:id/?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
campaign_id Identifier for campaign.
id Identifier for a specific redemption order to be updated.

Request Object

When this method runs, it passes in a request object that contains a redemption object, which contains a data object shown below:

▿ JSON Request

{
    "redemption": {
        "data" :{
            "location": "vending_machine"
        }
    }
}


This object is detailed in the following table:

Request Attributes for Data

Attribute Type
Required/Optional
Description
location string
required
Data created by customer when the redemption order is created through the POST or PUT route. Appears in the redemption object only when specified. Data reflects whatever attributes are configured in the redemption order; in this case, a string called location which specifies the location at which a redemption order was redeemed.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a redemption object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemption": {
    "id": 27,
    "expires_on": "2017-07-14T03:59:00Z",
    "status": "available",
    "data": {
      "location": "vending_machine"
    },
    "payload":
    {
      "test": true
    }
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found The user (customer) not found.
no_campaign_found The campaign was not found.
not_found Invalid redemption ID for user (customer).
missing_data Invalid or missing request data.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Reset a Redemption Order

Resets a redemption order, changing status from redeemed to available.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/redemptions/:id
DELETE /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:permalink/redemptions/:id
DELETE /api/v1/apps/:api_key/external/campaigns/:permalink/redemptions/:id?auth_token=xxxxxxxxx
DELETE /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:campaign_id/redemptions/:id
DELETE /priv/v1/apps/:api_key/users/:external_id/external/campaigns/:campaign_id/redemptions//:id
DELETE /api/v1/apps/:api_key/external/campaigns/:campaign_id/redemptions/:id/?auth_token=xxxxxxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Identifier for an internal customer.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
permalink Permanent link to external campaign.
campaign_id Identifier for campaign.
id Identifier for a specific redemption order to be deleted.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a redemption object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "redemption":
  {
    "id": 27,
    "expires_on": "2017-07-14T03:59:00Z",
    "status": "available",
    "payload":
    {
      "test": true
    }
  }
}

Statuses and Errors

For information, see Statuses and Errors.

Inbox API

Inbox objects create and send application inbox notifications that can be targeted to specific customers as well as, en masse, to the organization as a whole. Messages for customers are stored in a customer-specific inbox. They represent scheduled and targeted content of any kind: messaging, promotions, games and display advertising.

The endpoints allow an organization to manage the typical procedural flow of notifications for its customers. In addition to messages being sent, they can be retrieved for display to customers; they can be updated and deleted; and, they can be marked "read".

This API provides the following methods:

Create an Organization Inbox Message

Generates an inbox message for all customers in the organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/messages

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

When this method runs, it passes in a request object that contains the message object, which is the payload to create the message, as shown below:

▿ JSON Request

{
   "message":{
      "subject":"Foo",
      "external_id":"foo",
      "image":"http://images.foo.com/sessionM_M.png",
      "state":"live",
      "weight":60,
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "targeting":{
         "user.gender":{
            "#eq":"m"
         }
      }
   }
}


This object is detailed in the following table:

Request Attributes for Message

Attribute Type
Required/Optional
Description
subject string
required
Subject of the message.
external_id string
required
External message ID. Unique identifier to keep track of the message.
image string
optional
Valid URL of an icon to use for the message. Usually a square icon 50x50; or if handled by a developer, it can be any custom size.
state string
required
State of the message:

Organization inbox message state, includes:
live, preview

Customer inbox message:
new, read, deleted
weight integer
optional
The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions.

Default:
90
expires_on datetime
optional
Expiration time when the message will no longer persist in the inbox.
data object
required
Body of the message specified in the body attribute.
metadata object
optional
Any additional metadata (key-value pairs) to add to the message; supports use of rich display.
targeting object
optional
Customer targeting settings such as gender.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a message object, as shown below:

▿ JSON Response

{
   "status":"ok",
   "message":{
      "id":2,
      "external_id":"foo",
      "subject":"Foo",
      "type":"inbox",
      "state":"live",
      "weight":60,
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "targeting":{
         "user.gender":{
            "#eq":"m"
         }
      },
      "created_at":"2016-10- 04 20:23:43",
      "updated_at":"2016-10- 04 20:23:43"
   }
}


This object is detailed in the following table:

Response Attributes for Message

Attribute Type Description
id integer Message identifier.
external_id string
optional
External message ID. Unique identifier to keep track of the message.
subject string
optional
Subject of the message.
type string Type of message, inbox.
state string State of the message:

Organization inbox message state, includes:
live, preview

Customer inbox message:
new, read, deleted
weight integer The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions.

Default:
90
data object Body of the message specified in the body attribute.
metadata object Any additional metadata (key-value pairs) to add to the message; supports use of rich display.
targeting object Customer targeting settings such as gender.
created_at datetime The time the message was created.
updated_at datetime The time the message was updated.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Update an Organization Inbox Message

Updates an inbox message for all customers in an organization. One of the typical updates is setting the request object's status attribute to read.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/messages/:message_id
PUT /priv/v1/apps/:api_key/external/messages/:external_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id Internal identifier for the message.
external_id External message ID. Unique identifier for a message in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a message object, as shown in two samples below:

▿ JSON Request (Modify Message)

{
   "message":{
      "subject":"New Name"
   }
}

▿ JSON Request (Mark Message "Read")

{
  "message":{
    "state":"read"
  }
}

Response Object

In addition to a status key-value pair, this response object contains a message object, as shown in the samples below:

▿ JSON Response (Modified Message)

{
   "status":"ok",
   "message":{
      "id":18,
      "external_id":"foo",
      "subject":"New Name",
      "type":"inbox",
      "state":"live",
      "weight":0,
      "data":{
         "body":"body"
      },
      "metadata":{
         "tag":"value"
      },
      "created_at":"2016-10- 03 16:53:19",
      "updated_at":"2016-10- 05 16:55:07"
   }
}

▿ JSON Response (Message Marked "Read")

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "read",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Organization Inbox Messages

Retrieves inbox messages for an organization; the endpoints can specify either all of the messages or one in particular. For example, adding the parameter message_id to the GET /priv/v1/apps/:api_key/messages endpoint retrieves the specified message.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/messages
GET /priv/v1/apps/:api_key/messages/:message_id
GET /priv/v1/apps/:api_key/external/messages/:external_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id Returns just the specified message using the internal message ID.
external_id Returns just the specified message using the external message ID.

Request Object

When this method runs, it passes in a request object, as shown below:

▿ JSON Request

{
   "page": 1,
   "limit": 1
}


This object is detailed in the following table:

Request Attributes

Attribute Type
Required/Optional
Description
page integer
optional
Page to return for organization message. Default is 1. Example: page=2.
limit integer
optional
Maximum messages to receive for organization or customer inbox message.

Response Object

In addition to a status key-value pair, this object contains a messages array, as shown below:

▿ JSON Response

{
   "status":"ok",
   "messages":[
      {
         "id":20,
         "external_id":"foo2",
         "subject":"Foo2",
         "type":"inbox",
         "state":"live",
         "weight":0,
         "created_at":"2016-10- 05 16:58:57",
         "updated_at":"2016-10- 05 16:58:57"
      }
   ]
}


This object is detailed in the following table:

Response Attributes for Messages

Attribute Type Description
id integer Message identifier.
external_id string
optional
External message ID. Unique identifier to keep track of the message.
subject string
optional
Subject of the message.
type string Type of message, inbox.
state string State of the message:

Organization inbox message state, includes:
live, preview

Customer inbox message:
new, read, deleted
weight integer The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions.

Default:
90
created_at datetime The time the message was created.
updated_at datetime The time the message was updated.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete an Organization Inbox Message

Deletes inbox messages for an organization; the endpoints can specify either all of the messages or one in particular.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/messages/:message_id
DELETE /priv/v1/apps/:api_key/external/messages/:external_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id Returns just the specified message using the internal message ID.
external_id Returns just the specified message using the external message ID.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a message object, as shown below:

▿ JSON Response

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "deleted",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}


Note that if the message was successfully deleted, the state attribute in the response object is set to deleted.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Customer Inbox Message

Generates an inbox message for a single customer in the organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/external/users/:external_id/messages
POST /priv/v1/apps/:api_key/users/:user_id/messages

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id Identifier for the specified message using the internal message ID.
external_id Identifier for a customer in an external system creating a message.
user_id Internal identifier for the customer whose messages are all being updated in bulk within the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a message object, as shown below:

▿ JSON Request

{
   "message":{
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      }
   }
}

Response Object

In addition to a status key-value pair, this object contains a message object, as shown below:

▿ JSON Response

{
   "status":"ok",
   "message":{
      "id":"9bc36976-8b11- 11e6-8932- 43f360cca317",
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "state":"new",
      "type":"inbox",
      "created_at":"2016-10- 05T15:40:52Z"
   }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Update a Customer Inbox Message

Updates an inbox message for a specified customer in an organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
PUT /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id Identifier for a customer in an external system updating a message.
message_id Message identifier.
user_id Internal identifier for the customer within the SessionM Platform getting an updated message.

Request Object

When this method runs, it passes in a request object. This object contains a message object, as shown below:

▿ JSON Request

{
   "message":{
      "state":"read"
}

Response Object

In addition to a status key-value pair, this object contains a message object, as shown below:

▿ JSON Response

{
   "status":"ok",
   "message":{
      "id":"9bc36976-8b11- 11e6-8932- 43f360cca317",
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "state":"read",
      "type":"inbox",
      "created_at":"2016-10- 05T15:40:52Z"
   }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Customer Inbox Messages

Retrieves inbox messages for a customer in an organization; the endpoints can specify either all of the messages or one in particular. For example, adding the parameter message_id to either the GET /priv/v1/apps/:api_key/external/users/:external_id/messages or the GET /priv/v1/apps/:api_key/users/:id/messages endpoint retrieves the specified message.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/external/users/:external_id/messages
GET /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
GET /priv/v1/apps/:api_key/users/:user_id/messages
GET /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id Identifier for a customer in an external system receiving a message.
message_id Message identifier.
user_id Internal identifier for the customer within the SessionM Platform receiving a message.

Request Object

When this method runs, it passes in a request object shown below:

▿ JSON Request

{
   "limit": 29
}


This object is detailed in the following table:

Request Attributes

Attribute Type
Required/Optional
Description
limit integer
optional
Maximum messages to receive for organization or customer inbox message.
from string
optional
Customer inbox message time, or UUID.

Response Object

In addition to a status key-value pair, this object contains a messages array, as shown below:

▿ JSON Response

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "subject":"message4",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 06T15:47:43Z"
      },
      {
         "id":"0db644d0-8b13- 11e6-803a- e8e460cca317",
         "subject":"message2",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 05T15:47:43Z"
      }
   ],
   "pagination":{
      "from":"e302804c-8a49- 11e6-89b1- 56cd60cca317"
   },
   "status":"ok"
}


The second child object in the response is named pagination; this object contains the from attribute, which is a string that specifies the message time.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Customer Inbox Message

Deletes an inbox message for a customer in an organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
DELETE /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id Identifier for a customer in an external system deleting a message.
message_id Message identifier.
user_id Internal identifier for the customer within the SessionM Platform deleting a message.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, this object contains a message object, as shown below:

▿ JSON Response

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "deleted",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}


Note that if the message was successfully deleted, the state attribute in the response object is set to deleted.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Bulk Update Customer Inbox Messages

Updates in bulk all of the messages specified in the associated array of request objects.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/:api_version/apps/:api_key/users/:user_id/messages
PUT /priv/:api_version/apps/:api_key/external/users/:external_id/messages

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer whose messages are all being updated in bulk within the SessionM Platform.
external_id External identifier for the customer whose messages are all being updated in bulk in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a messages object, as shown below:

▿ JSON Request

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "state":"read"
      }
   ]
}


This object's attributes are documented in the following table:

Request Attributes

Attribute Type
Required/Optional
Description
id integer
required
Message identifier.
state string
required
State of the message:

Organization inbox message state, includes:
live, preview

Customer inbox message:
new, read, deleted.

Response Object

In addition to a status key-value pair, this object contains a messages array, as shown below:

▿ JSON Response

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "subject":"message4",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 06T15:47:43Z"
      },
      {
         "id":"0db644d0-8b13- 11e6-803a- e8e460cca317",
         "subject":"message2",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 05T15:47:43Z"
      }
   ],
   "pagination":{
      "from":"e302804c-8a49- 11e6-89b1- 56cd60cca317"
   },
   "status":"ok"
}


The second child object in the response is named pagination; this object contains the from attribute, which is a string that specifies the message time.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code Reason
message_not_found Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Loyalty

The APIs featured in this grouping enable organizations to incentivize customers to stay engaged with long-term and expanding customer loyalty programs. Services manage a variety of entities that are critical to building consumer loyalty, including APIs for the following:

All of the sections that follow document these APIs, except for the first. The section below details how enabling loyalty settings can influence response objects returned by many APIs.

Effects of Loyalty Settings on Response Objects

As an organization builds out its SessionM implementation, a powerful interdependence develops between the data served by loyalty APIs and the data that expresses information about customers.

When loyalty settings are enabled and loyalty data exists, additional attributes are introduced to response objects across the platform. Many of these objects contain attributes that correspond to a customer's access and redemption of credit, which often manifests as points.

For example, the Rewards Store API exposes a method that retrieves all rewards for an organization or with respect to a specified customer, and the Orders API contains a method for creating orders for those rewards. In accord with these activities, the Points API tracks the history of a customer accumulating and redeeming these points. Over time, a variety of transactions can occur, and, as they do, the associated customer's points balance increases and decreases.

Since these balances belong to customers, many of the JSON responses that reflect express customer data contain attributes related to loyalty balances. Whether or not such data displays in the JSON responses is governed by the enable_mpoints_info_in_customers_api setting, which is accessed via the SessionM Admin Portal. For more information, consult your Customer Success contact.

The sections below discuss the conditional attributes that can be enabled for each of the relevant APIs.

Loyalty Data in Customer Objects

Loyalty data can augment customer objects within JSON responses returned by the following APIs:

When the enable_mpoints_info_in_users_api setting is enabled, the customer data in response objects can be augmented by two attributes: available_points, an integer that specifies the number of points available to the customer; and unclaimed_achievement_count, an integer that specifies the number of unclaimed points currently available to the customer.

One example of this condition is the response object shown below, which is returned when retrieving an authorization token with a custom profile:

JSON Response Object with Loyalty Settings Enabled

{
    "status": "ok",
    "user": {
        "account_status": "good",
        "auth_token": "v2--5W8kaVGHoUpxcm98nrmtp287KVHZChE9hXWaagYeXJw=--hUvxfLBwMdTBUCwiYLSi7YNv6gMOYQYsOZJyxM1OjemkAR0K9dqRj6f-hvei1K8MNA==",
        "available_points": 0,
        "created_at": "2016-10-21 18:12:22",
        "dob": "1980-01-01",
        "email": "john.smith@fake.email.addr",
        "external_id": "654321",
        "gender": "m",
        "id": "e9c2bbfe-97b9-11e6-9663-271bc1d29f66",
        "proxy_ids": [],
        "registered_at": "2016-10-21 18:12:22",
        "suspended": false,
        "unclaimed_achievement_count": 0,
        "updated_at": "2016-10-21 18:12:22",
        "user_profile": {
          "_version": 1,
          "user_title":"mr",
          "program_tier":4,
          "locale":"fr-ca"
       }
    }
}


The following table provides details on each of the conditions for which a user object in a JSON response contains loyalty data:

API Endpoints Description
Authorization Tokens GET /priv/v1/apps/:api_key/users/:user_id?user[auth_token]=true
GET /priv/v1/apps/:api_key/external/users/:external_id?user[auth_token]=true
GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true&user[auth_token]=true
GET /priv/v1/apps/:api_key/external/users/:external_id?user[user_profile]=true&user[auth_token]=true
Loyalty data resides in JSON response objects returned by endpoints that retrieve authorization tokens with either a standard or custom profile.
Standard Profile POST /priv/v1/apps/:api_key/users
GET /priv/v1/apps/:api_key/users/:user_id
GET /priv/v1/apps/:api_key/external/users/:external_id
GET /priv/v1/apps/:api_key/users/
PUT /priv/v1/apps/:api_key/users/:user_id
PUT /priv/v1/apps/:api_key/external/users/:external_id
DELETE /priv/v1/apps/:api_key/users/:user_id
GET /priv/v1/apps/:api_key/users/search?email=test@example.com
Loyalty data resides in JSON response objects returned by endpoints that create, retrieve, update, delete or search standard profiles.
Custom Profile PUT /priv/v1/apps/:api_key/users/:user_id
GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true
Loyalty data resides in JSON response objects returned by endpoints that retrieve or update combined standard and custom profiles.
Places POST /priv/v1/apps/:api_key/places/:place_id/check_ins
POST /priv/v1/apps/:api_key/users/:user_id/places/:place_id/check_ins
Loyalty data resides in JSON response objects returned by endpoints that check a user into a place.
Events POST /priv/v1/apps/:api_key/users/:user_id/events
POST /priv/v1/apps/:api_key/users/:user_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/events
POST /priv/v1/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/events
POST /priv/v1/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/events
Loyalty data resides in JSON response objects returned by endpoints that create basic activity and purchase events.

Loyalty Data in Eligible Campaigns Objects

Loyalty data can augment JSON responses returned by the Eligible Campaigns API.

Provided there are points-related activities (points orders) in the system, the points array is part of the returned activities object; if no activities exist, the data for that section is omitted. The points array contains objects with the following attributes: behavior_id, an integer that specifies the action identifier; campaign_id, an integer for the internal campaign identifier; points, an integer that specifies any existing point values; transaction_id, a string that specifies an identifier for the transaction that triggered the action; and type, a string that specifies the type of action.

This condition applies to the response object shown below, which is returned when retrieving a customer's completed activities:

JSON Response Object with Loyalty Settings Enabled

{
  "activities": {
    "points": [
    {
      "behavior_id": 8591,
      "campaign_id": 4197,
      "points": 0,
      "transaction_id": "30114377",
      "type": "points"
    } ],
    "orders": [
    {
      "id": 2343,
      "campaign_id": 4198,
      "receipt_id": 3453,
      "behavior_id": 3234,
      "type": "offer",
      "header": "offer header",
      "subheader": "offer subheader",
      "description": "this is an offer description",
      "icon_url": "http://www.aniconhere.com",
      "image_url": "http://www.animagehere.com",
      "redeem_url": "http://www.aredeemhere.com",
      "state": "reviewed",
      "offer_id": 235
    } ]
  }
}


The following table provides details on the condition for which an activities object in a JSON response contains loyalty data:

API Endpoints Description
Eligible Campaigns GET /priv/v1/apps/:api_key/users/:user_id/activities
GET /priv/v1/apps/:api_key/external/users/:external_id/activities
Loyalty data resides in JSON response objects returned by endpoints that retrieve completed activities for a customer.

Rewards Store API

In the SessionM Platform, the Rewards Store API contains a few endpoints for retrieving a list of rewards (represented by offer objects) available either across an organization or to a specific customer. Individual customers can purchase items in a client's digital rewards store by redeeming points or other loyalty currency.

While rewards can be made available to an organization, whether or not a specific customer can redeem points or other loyalty currency for a reward is subject to several factors such as a customer's age and point balance. For example, if the customer has insufficient points for the redemption, the reward will not be redeemable for them, though they can still see it in the store view. For information on how this API's endpoints determine how the response object is structured, see "Endpoint Parameters" section below.

Reward types largely match incentive types, as both, at their core, are simply things of value. Incentive types include:

This assortment of reward types allows clients to design reward stores that motivate customers to complete those actions that earn them points, while SessionM can provide all the services necessary to fulfill orders for any of these reward types. Note that SessionM can provide several services: reporting that details customer order histories, and internationalization so that orders can be in multiple languages and countries.

Used for rewards stores, this API can reward customers in some type of loyalty program in which they can earn points. The act of redeeming points or other loyalty currency for a reward boosts engagement in promotional programs.

This API provides a method that returns a list of rewards available to either an organization's customer base or to a specific customer. Note that rewards are created via the SessionM Administration Portal, not via this API.

Retrieve a List of Rewards for an Eligible Customer

Retrieves a list of rewards available to either an organization's customer base or to a specific customer. Note that the endpoints that utilize only the api_key and a locale, with (or without) a user_id or an external_id, are available for registered customers (users); however, GET /api/v1/apps/:api_key/offers?auth_token=xxxxx applies to unregistered, anonymous customers.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/offers?locale=en-us
GET /priv/v1/apps/:api_key/users/:user_id/offers?locale=es-us
GET /priv/v1/apps/:api_key/external/users/:external_id/offers?locale=en-ca
GET /api/v1/apps/:api_key/offers?auth_token=xxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
locale Used for internationalization.

If you choose to specify only the api_key parameter in the endpoint, this method returns all of the rewards defined for the organization.

If you choose to supplement the api_key with either the user_id or external_id parameter in the endpoint, this method returns the rewards as they correspond to a specific customer. The reward's availability is shown in the response object (featured below) returned by the method; in particular, its availability displays in the offer object's status attribute. For more information on the offer object in a response and its status attribute, see the "Response Object" section below along with Reward Statuses.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an offer object, as shown below:

▿ JSON Response

{
   "status": "ok",
   "offer":
     {
      "id":4321,
      "name":"Name of offer",
      "type":"merchandise",
      "description":"a description",
      "points":100,
      "start_time":"2016-02-02T17:08:29Z",
      "end_time":"2016-03-02T17:08:29Z",
      "weight": 100,
      "featured": true,
      "tier":"gold",
      "status":"verification_required",
      "requires_skills_test":false,
      "logo":"http://content.sessionm.com/offers/2/logo.png",
      "data":{ "example" : "example" },
      "options":[
         {
            "id":2,
            "name":"Name of offer variant A",
            "type":"offer",
            "description":"A high level description",
            "points":100,
            "start_time":"2016-02-02T17:08:29Z",
            "end_time":"2016-03-02T17:08:29Z",
            "weight": 100,
            "featured": true,
            "tier":"gold",
            "status":"verification_required",
            "requires_skills_test":false,
            "logo":"http://content.sessionm.com/offers/2/logo.png",
            "data":{ "example" : "example" }
         },
         {
            "id":3,
            "name":"Name of offer variant B",
            "type":"offer",
            "description":"A high-level description",
            "points":100,
            "start_time":"2016-02-02T17:08:29Z",
            "end_time":"2016-03-02T17:08:29Z",
            "weight": 200,
            "featured": true,
            "tier":"gold",
            "status":"verification_required",
            "requires_skills_test":false,
            "logo":"http://content.sessionm.com/offers/2/logo.png",
            "data":{ "example" : "example" }
             }
      ]
   }
}


The following table documents this object:

Response Attributes for Reward (Formerly Offer)

Attribute Type Description
id string Internal reward identifier.
name string Name of the reward.
type string Available reward types. Default ones include: offer, prize, coupon, instant reward, and contest entries. However, free-form attributes can contain others.
description string Description of reward.
points integer Amount of points, or other loyalty currency, associated with reward.
start_time string Datetime at which reward begins. ISO 8601 format. For example: 2016-02-02T17:08:29Z.
end_time string Datetime at which reward ends. ISO 8601 format. For example: 2016-02-02T17:08:29Z.
weight integer Arbitrary numeric value which allows for sorting items.
featured boolean Used to identify a prominent reward for display.
tier string Tiers within a tier system.
tier_system string Tier systems in enterprise client.
status string Status of reward with respect to customer. For more information on reward statuses, see the table below.
requires_skills_test boolean Required for Canadian contests.
logo string An image-based URL for reward.
terms string Terms of reward agreement.
data object Free form hash for client-specific needs.
options array Child rewards. For example small, medium, large sizes.

Reward Statuses

The following status values can be returned in the offer object within a response representing a reward:

Code Reason
available Reward is available for redemption by the customer.
verification_required Customer is not yet verified and verification is needed prior to redemption.
not_qualified The customer does not meet the qualification requirement for the reward - for example the customer might be a minor.
insufficient_points The reward redemption value is higher than the current available points for the customer.
user_required Cannot determine the status of this reward against a customer without a customer ID.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid_api_key API key sent in cannot be found.
user_not_found Customer ID sent in cannot be found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Skills Test Challenge API

Challenge objects allow jurisdictions to require that a sweepstakes entry be gated by a skills test. A reward can employ this logic to require a skills test that approves mental ability or competency. For example, the laws governing Canadian contests require that a skills test be used to qualify customers redeeming a reward. Skills test challenge questions are selected randomly from a pool of questions.

If the customer answers with the wrong answer, no error is returned; the customer is not entered in the sweepstakes and the points used to enter the challenge for the sweepstakes are forfeited.

This API provides the following methods:

Retrieve a Skills Test Challenge Question

Retrieves a skills test challenge question.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/challenges/skills_test_question
GET /priv/v1/apps/:api_key/external/users/:external_id/challenges/skills_test_question

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a challenge object, which in turn contains a skills_test_question object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "challenge": {
    "skills_test_question": {
      "id": 100,
      "question": "(2+2) + (2-2)"
    }
  }
}


This object is detailed in the following table:

Response Attributes for Skills Test Question

Attribute Type Description
id integer Skills test ID.
question string Skill test question.
response string Skill test question response.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid Skills test question was answered incorrectly
skills_test_not_found Skills test ID sent in was not found

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Skills Test Challenge Question

Specifies a skills test challenge question.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/offers/:offer_id/challenges/skills_test_questions/:skills_test_question_id
POST /priv/v1/apps/:api_key/external/users/:external_id/offers/:offer_id/challenges/skills_test_questions/:skills_test_question_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
offer_id Identifier for reward associated with skills test challenge.
skills_test_challenge_id Identifier for skills test challenge question.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a challenge object, which contains a skills_test_question object, shown below:

▿ JSON Request

{
  "challenge": {
    "skills_test_question": {
      "response": "1"
    }
  }
}


These objects are detailed in the following tables:

Request Attributes for Challenge

Attribute Type
Required/Optional
Description
skills_test_question object
required
Skills test question, which contains a response attribute detailed in the next table.

Request Attributes for Skill Test Question

Attribute Type
Required/Optional
Description
response integer
required
Skills test question response.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a challenge object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "challenge": {
    "id": 1111111,
    "status": "valid"
  }
}


This object is detailed in the following table:

Response Attributes for Challenge

Attribute Type Description
id integer Challenge ID.
status string Skills test challenge result: valid or invalid.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Referrals API

Referral objects provide the means to run a refer-a-friend program. These programs must be set up initially in the platform before you can begin using the Referrals API to add incentives to them. Each refer-a-friend program can implement a set of custom rules.

Referrals objects allow an enterprise client to create referrals and retrieve their details. Each referral requires a referrer and at least one referee. A referrer is an existing SessionM customer that wants to notify other people about a promotion; a referee is the person (or people) receiving the referral.

A referral object includes the referrer, along with their email, telephone number, and the name of their associated referee(s).

This API provides the following methods:

Create Referrals

Builds referrals for one or multiple referees based on a referrer. The data entered for the referrer attribute will determine how the referrer is referenced by the referee. The referee is addressed in a greeting with the data contained in the referee attribute.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/referrals
POST /priv/v1/apps/:api_key/external/users/:external_id/referrals

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains the referrer attribute (required string), along with a referrals array, as shown below:

This array is detailed in the following table:

▿ JSON Request

{
  "referrer": "referrer name/id shown to the referee",
  "referrals": [
    {
      "referee": "referee name/id for greeting (optional)",
      "email": "example1@example.com",
      "tel": "617-555-1212"
    },
    {
      "referee": "referee name/id for greeting (optional)",
      "email": "example21@example.com",
      "tel": "617-555-1213"
    }
  ]
}



This object is detailed in the following table:

Request Attributes for Referrals

Attribute Type
Required/Optional
Description
referee string
required
Referee name/ID for the greeting.
email string
required
Email address of referee. Data is encrypted for storage on the disk.
tel string
required
Telephone number of referee.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the referrals object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "referrals": [
    {
      "id": "identifier for the created referral",
      "referee": "referee name/id for greeting (optional)",
      "email": "example1@example.com",
      "tel": "617-555-1212",
      "origin": "",
      "source": "12345",
      "client_data": "opaque client data",
      "status": "pending",
      "pending_at": "2017-01-01T02:04:55.126Z",
      "engaged_at": null,
      "registered_at": null,
      "converted_at": null,
      "voided_at": null,
      "conversion_points": 0
    },
    {
      "id": "identifier for the created referral",
      "referee": "referee name/id for greeting (optional)",
      "email": "example21@example.com",
      "tel": "617-555-1213",
      "origin": "",
      "source": "12345",
      "client_data": "opaque client data",
      "status": "pending",
      "pending_at": "2017-01-01T02:04:55.126Z",
      "engaged_at": null,
      "registered_at": null,
      "converted_at": null,
      "voided_at": null,
      "conversion_points": 0
    }
  ]
}


The following table documents this object:

Response Attributes for Referrals

Attribute Type Description
id integer Identifier for the referral.
referee string Referee name/ID for greeting.
email string Referee's email address. Data is encrypted for storage on the disk.
tel string Referee's telephone number.
client_data string Opaque client data.
status string Status of the initial referral is pending, but could be any of the following: pending, engaged, registered, converted, limit_period, limit_lifetime, and voided.
pending_at datetime Time the referral became pending.
engaged_at datetime Time the referral became engaged.
registered_at datetime Time the referral became registered.
converted_at datetime Time the referral became converted.
voided_at datetime Time the referral became voided.
conversions_points integer Identifier for the referral.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
referral_email_required Email is required.
referral_registered_email Email already in use.
missing_data No referrals specified.
validation Limit for referrals in a month exceeded.
referral_duplicate_email Limit for referrals for the customer exceeded.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Referrals

Returns all referrals a customer has made, based customer ID or the enterprise client’s external ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/referrals
GET /priv/v1/apps/:api_key/external/users/:external_id/referrals

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

This method returns a response object that begins with status and cursor key-value pairs, both of which are strings. When the cursor value is null, there is no more data.

Then the response shows a referral array, as shown below:

▿ JSON Response

{
  "status": "ok",
  "cursor": "cursor value (null means no more data)",
  "referral": [
    {
      "id": "identifier for the referral",
      "referee": "referee name/id for greeting (optional)",
      "email": "example1@example.com",
      "tel": "555 1212",
      "origin": "",
      "source": "12345",
      "client_data": "opaque client data",
      "status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
      "pending_at": "2017-01-01T02:04:55.126Z",
      "engaged_at": "2017-01-01T02:04:55.126Z",
      "registered_at": "2017-01-01T02:04:55.126Z",
      "converted_at": "2017-01-01T02:04:55.126Z",
      "voided_at": "2017-01-01T02:04:55.126Z",
      "conversion_points": 10
    },
    {
      "id": "identifier for the referral",
      "referee": "referee name/id for greeting (optional)",
      "email": "example1@example.com",
      "tel": "555 1212",
      "origin": "",
      "source": "12345",
      "client_data": "opaque client data",
      "status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
      "pending_at": "2017-01-01T02:04:55.126Z",
      "engaged_at": "2017-01-01T02:04:55.126Z",
      "registered_at": "2017-01-01T02:04:55.126Z",
      "converted_at": "2017-01-01T02:04:55.126Z",
      "voided_at": "2017-01-01T02:04:55.126Z",
      "conversion_points": 10
    }
  ]
}



For information on this object, see the referrals object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve a Single Referral

Retrieves information for a single referral based on customer ID and referral ID or the enterprise client customer’s external ID and referral ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/referrals/:referral_id
GET /priv/v1/apps/:api_key/external/users/:external_id/referrals/:referral_id


Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
referral_id Identifier for the referral.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a referral object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "referral": {
    "id": "identifier for the referral",
    "referee": "referee name/id for greeting (optional)",
    "email": "example@example.com",
    "tel": "555 1212",
    "origin": "",
    "source": "12345",
    "client_data": "opaque client data",
    "status": "pending|engaged|registered|converted|limit_period|limit_lifetime|voided",
    "pending_at": "2017-01-01T02:04:55.126Z",
    "engaged_at": "2017-01-01T02:04:55.126Z",
    "registered_at": "2017-01-01T02:04:55.126Z",
    "converted_at": "2017-01-01T02:04:55.126Z",
    "voided_at": "2017-01-01T02:04:55.126Z",
    "conversion_points": 10
  }
}


For information on this object, see the referrals object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
referral_not_found Referral doesn't exist; referral ID not found.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Loyalty Card API

The Loyalty Card API offers Loyalty Card and Retailers objects to allow third-party systems to link their loyalty cards to an enterprise client standard customer profile, which is often called a customer account. Many retailers issue loyalty cards to their customers that are then swiped at the register for point of sale discounts on select products.

The API offers a way to read loyalty card transactions and in turn award points that correspond with what the customer purchases.

The workflow resembles the point of sale transactions managed by the Events API. Just as the Events API offers a purchase event type, the Loyalty Card API treats transactions from loyalty card providers as purchase events run against - or processed against - active campaigns.

Loyalty cards can be linked to campaigns. Within a campaign, incentives and different types of messaging can be outcomes of specific purchase actions. This type of link must be configured via the Administration Portal in advance, as they are not managed by the Campaigns API.

This API provides the following methods:

Create an On-demand Loyalty Card

Creates a digital loyalty card identifier and associates it to a customer in real time. This method is executed for a single customer, one at a time and on-demand.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/loyalty_cards
POST /priv/v1/apps/:api_key/external/users/:external_id/loyalty_cards

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "loyalty_card": {
    "id": 23,
    "user": {
      "id": "4f5b82c0-07c8-11e6-8d84-624132d14633"
    },
    "card_type": "digital_card",
    "last_activated_at": "2016-12-06T20:45:16Z",
    "number": "DBEDTFK6DD"
  }
}


This object is detailed in the following table:

Response Attributes for Loyalty Card

Attribute Type Description
id integer Loyalty card identifier.
user object Contains id, which identifies a customer; or external_id, which identifies a customer in an external system. Can include available_points attribute when the customer has accumulated loyalty points.
card_type string Loyalty card type. For these endpoints, digital_card, which is a purely digital loyalty card number.
last_activated_at datetime Most recent activation or linkage. Complies with ISO8601 datetime.
last_scanned_at datetime Most recent scan. Complies with ISO8601 datetime.
number string Loyalty card decrypted number.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
card_type_is_not_ondemand The generation attribute in the loyalty card policy is not on-demand.
alphabet_contains_duplicates_characters_for_policy The alphabet attribute in the loyalty card policy has duplicate characters.
max_iterations_reached Maximum number of loyalty cards have been connected for the given customer.
no_alphabet_available_for_policy General catch-all validation error.
invalid_card_type_for_policy Maximum number of iterations has been reached for generating the unique on-demand card.
max_cards_exceeded_for_player The customer has exceeded the maximum number of active cards that a customer may have at one time.
no_max_active_cards_per_player_available_for_policy The max_active_cards_per_player attribute in the loyalty card policy is not defined.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Specifies a link between a retailer’s loyalty card and a customer’s standard profile, often called a customer account.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/loyalty_links
POST /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a loyalty_card object, as shown below:

▿ JSON Request

{
   "loyalty_card":{
      "retailer_id":"54321",
      "card_number":"12345"
   }
}



This object is detailed in the following table:

Request Attributes for Loyalty Card

Attribute Type
Required/Optional
Description
retailer_id string
required
Unique retailer identifier.
card_number string
required
Unique loyalty card identifier.

▿ JSON Response

{
   "status":"ok",
   "loyalty_card":{
      "id":12345
   }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains a loyalty_card object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
card_not_found The passed in loyalty card number could not be located.
retailer_code_invalid US zip codes are currently supported.
card_limit_reached Max number of cards have been connected for the given customer.
validation General catch all validation error.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a List of Participating Retailers

Returns a list of retailers that can be linked to a standard profile for a customer. If using an endpoint with user_id, it will return retailers linked to a specific customer’s standard profile. You can also set an endpoint parameter that retrieves all retailers for the specified zip code. Note that the endpoints that utilize anonymous_index, user_id or external_id, are available for registered customers (users); however, GET /api/v1/apps:/api_key/loyalty_retailers?auth_token=xxxxx applies to unregistered, anonymous customers.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/loyalty_retailers/anonymous_index?zip=12345
GET /priv/v1/apps/:api_key/users/:user_id/loyalty_retailers?zip=12345
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_retailers?zip=12345
GET /api/v1/apps:/api_key/loyalty_retailers?auth_token=xxxxx

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
zip Returns retailers within zip or postal code; returns all retailers by default. For example, zip=12345.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a retailers object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "retailers": [
    {
      "id": 111111,
      "name": "ACME",
      "card": "ACME Card",
      "icon": "https://....",
      "image": "https://....",
      "linked": true,
      "barcode_scannable": true
    },
    {
      "id":222222,
      "name": "Rx Inc.",
      "card": "Rx Card",
      "icon": "https://....",
      "image" : "https://....",
      "linked": false
    }
  ]
}


This object is detailed in the following table:

Response Attributes for Retailers

Attribute Type Description
id integer Loyalty retailer ID.
name string Retailer name.
card string Loyalty card name.
icon string Retailer icon URL. Dimensions can vary.
image string Retailer feature image URL. Dimensions can vary.
linked boolean If the retailers endpoint is requested with a customer or external ID, linked indicates if the customer has a loyalty card linked against this retailer.
barcode_scannable boolean If the barcode is set by the retailer (on the LoyaltyRetailer object) and is scannable, the value can be sent back to the API. true if the barcode is scannable; false if it's not.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
retailer_code_invalid When an invalid zip or postal code is entered.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve a List of Linked Loyalty Cards

Retrieves a list of loyalty cards linked to a specific standard customer profile.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/loyalty_links
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a loyalty_cards array, which includes a set of loyalty_card objects, as shown below:

▿ JSON Response

{
   "status":"ok",
   "loyalty_cards":[
      {
         "id":12345,
         "card_number":"12345",
         "retailer":{
            "id":"54321",
            "name":"ACME",
            "icon":"https://....",
            "image":"https://...."
         }
      },
      {
         "id":12345,
         "card_number":"456789",
         "retailer":{
            "id":"54321",
            "name":"Rx Inc.",
            "icon":"https://....",
            "image":"https://...."
         }
      }
   ]
}


This array is detailed in the following table:

Response Attributes for Loyalty Cards

Attribute Type Description
id integer Loyalty Card ID.
card_number string Loyalty card number.
retailer object For more information, see the retailers array.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Loyalty Card Transactions

Retrieves loyalty card transactions.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/loyalty_transactions
GET /priv/v1/apps/:api_key/external/users/:external_id/loyalty_transactions

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
limit Default is 100.
page Default is 1.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a loyalty_transactions array, as shown below:

▿ JSON Response

{
   "status":"ok",
   "loyalty_transactions":[
      {
         "id":201,
         "name":"3600000011",
         "description":"Product 3600000011",
         "price":10.0,
         "quantity":1,
         "transaction_datetime":"2016-05-26 17:23:46",
         "points":10,
         "created_at":"2016-05-26 17:23:46",
         "updated_at":"2016-05-26 17:23:46"
      },
      {
         "id":206,
         "name":"3600000016",
         "description":"Product 3600000016",
         "price":10.0,
         "quantity":1,
         "transaction_datetime":"2016-05-26 17:23:46",
         "points":10,
         "created_at":"2016-05-26 17:23:46",
         "updated_at":"2016-05-26 17:23:46"
      }
   ]
}


This array is detailed in the following table:

Response Attributes for Loyalty Transactions

Attribute Type Description
id integer Loyalty transaction ID.
name string UPC/SKU code or product description.
description string Product description.
price float Price payed in the transaction.
quantity integer Number of product purchased.
transaction_datetime string Purchase date time in UPC.
points integer Points earned for the transaction.
created_at string Loyalty transaction creation UTC date time.
updated_at string Loyalty transaction last updated UTC date time.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
requires_registered_user Registed customers are required for this request.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Deletes the link between a loyalty card and a standard customer profile.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/:api_version/apps/:api_key/users/:user_id/loyalty_links/:id
DELETE /priv/v1/apps/:api_key/external/users/:external_id/loyalty_links/:id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
id Loyalty Card ID.

Request Object

Not applicable.

Response Object

This method returns a response object that contains a status key-value pair, as shown below:

▿ JSON Response

{
   "status":"ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
card_not_found When an invalid loyalty_card ID is entered.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Scan a Loyalty Card

Scan a loyalty card. For example, a customer scanning their digital loyalty card with their mobile phone at a point-of-sale device in a retail coffee shop. A client application could then implement a workflow in which the action of scanning a card results in a discount being applied to a particular reward.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/loyalty_cards/:card_number

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
card_number Loyalty card number.

Request Object

Not applicable.

Response Object

Since this method’s response object is similar to what is returned for the method that creates an on-demand loyalty card, see the loyalty_card object for more information on the object which is shown below:

▿ JSON Response

{
  "status": "ok",
  "loyalty_card": {
    "id": 29,
    "user": {
      "external_id": "N/A",
      "available_points": 394160
    },
    "card_type": "digital_card",
    "last_activated_at": "2016-12-08T16:44:31Z",
    "last_scanned_at": "2016-12-08T19:20:25Z",
    "number": "D1QMCP2R2O"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
unknown_loyalty_card Loyalty card number does not exist.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Image Validation API

Image Validation objects allow a customer to submit images such as receipt captures for validation or photographs. Using this API, receipt capture images can be tracked through the validation process. The number of images per image validation record is configurable. SessionM can work with a variety of partners to validate receipts, but the API is validation provider agnostic.

Consider the following image format requirements:

Note that some setup and configuration is required before this API can be utilized. For more information, please contact your Customer Success representative for assistance.

This API provides the following methods:

Create a New Image Validation Record

Adds a new image validation record. This method allows customers to submit a receipt.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/image_validations?auth_token=xxxx-yyyy-zzzz
POST /priv/v1/apps/:api_key/users/:user_id/image_validations
POST /priv/v1/apps/:api_key/external/users/:external_id/image_validations

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

When this method runs, it passes in a request object that contains an image_validation object, which is shown below:

▿ JSON Request

{
  "image_validation": {
    "validation_type": "receipt",
    "campaign_permalink": "my-receipt-campaign",
    "placement_id" : 54321,
    "external_id" : "my-tracking-id",
    "images" : [
        { "id" : "100", "base64_data"  : "....", "mime_type" : "image/jpg" },
        { "id" : "101", "base64_data"  : "....", "mime_type" : "image/png" }
    ],
    "data" : {
    }
  }
}


This object is detailed in the following table:

Request Attributes for Image Validation

Attribute Type
Required/Optional
Description
validation_type string
required
Specifies validation type. Use "receipt" to explicitly specify a receipt capture and validation. Use “image" for regular image validation.
campaign_permalink string
required
SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id string
optional
Your placement ID. Format: placement_id=your-placement-id.
external_id string
optional
Use for local tracking.
image_count integer
optional
Used for uploading one image at a time through the /images route.
images array
required
Must be at least length 1.
data object
optional
Free form hash.

Note too that every image accepts an optional, client-defined ID for tracking purposes; these IDs are returned in the response.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an image_validation object, which is shown below:

▿ JSON Response

{
  "status": "ok",
  "image_validation": {
    "id": 111111,
    "validation_type": "receipt",
    "campaign_id" : 12345,
    "campaign_permalink" : "my-receipt-campaign",
    "placement_id" : 54321,
    "external_id" : "my-tracking-id",
    "user_id": "xxxxx",
    "status": "pending",
    "created_at": "2015-01-20 13:04:45",
    "updated_at": "2015-01-21 13:04:45",
    "image_count": 2,
    "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url": "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
    ],
    "data" : {
    }
  }
}


The following table documents this object:

Response Attributes for Image Validation

Attribute Type Description
id integer Image validation ID.
validation_type string Shows validation type: receipt to explicitly specify a receipt capture and validation; image for regular image validation.
campaign_id integer SessionM campaign identifier for the image. Each campaign has a defined set of rules and actions.
campaign_permalink string SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id string Your placement ID. Format: placement_id=your-placement-id.
external_id string Use for local tracking.
user_id string SessionM customer identifier.
status string One of pending, valid, invalid, incomplete.
created_at string Image validation creation UTC date time.
updated_at string Image validation last updated UTC date time.
image_count integer Used for uploading one image at a time through the /images route.
images array List of image objects attached to the image validation with URLs.
data object Free form hash.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data Required parameter is missing.
campaign_unavailable The campaign identifier sent in could not be found.
campaign_unavailable The customer is ineligible for this campaign or has hit the cap.
validation Customer has exceeded daily limit.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a New Image in an Image Validation Record

Adds a new image to an image validation record.

In more technical terms, it adds an image to an image validation record with a status of incomplete. It then returns an updated image validation object. Image validation objects with a status of incomplete change to pending once the initial image_count is reached.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /api/v1/apps/:api_key/image_validations/:image_validation_id/images?auth_token=xxxx-yyyy-zzzz
POST /priv/v1/apps/:api_key/users/:user_id/image_validations/:image_validation_id/images
POST /priv/v1/apps/:api_key/external/users/:external_id/image_validations/:image_validation_id/images

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

When this method runs, it passes in a request object that contains an image object, which is shown below:

▿ JSON Request

{
  "image" : {
    "id" : "101",
    "base64_data"  : "....",
    "mime_type" : "image/jpg"
  }
}


This object is detailed in the following table:

Request Attributes for Image

Attribute Type
Required/Optional
Description
id string
optional
Use for local tracking.
base64_data string
required
Base64 encoded image data.
mime_type string
optional
Mime type of the image.

Response Object

This object is identical to the response object returned for the method that creates a new validation record, as shown below:

▿ JSON Response

{
  "status": "ok",
  "image_validation": {
    "id": 111111,
    "validation_type": "receipt",
    "campaign_id" : 12345,
    "campaign_permalink" : "example",
    "placement_id" : 54321,
    "user_id": "xxxxx",
    "status": "pending",
    "created_at": "2015-01-20 13:04:45",
    "updated_at": "2015-01-21 13:04:45",
    "image_count": 2,
    "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url": "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
    ],
    "data" : {
    }
  }
}


For more information, see the image_validation object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
validation Invalid image data sent in.
image_not_found No image data sent in.
validation Too many images passed in.
validation An image passed in is over 10MB.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Image Validation Record

Retrieves an image validation record.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /api/v1/apps/:api_key/image_validations?auth_token=xxxx-yyyy-zzzz
GET /priv/v1/apps/:api_key/users/:user_id/image_validations
GET /priv/v1/apps/:api_key/external/users/:external_id/image_validations

Endpoint Parameters

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.
limit Default is 100.
page Default is 1.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an image_validations array, which is shown below:

▿ JSON Response

{
  "image_validations": [
    {
      "id": 111111,
      "validation_type": "receipt",
      "campaign_id" : 12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id" : "xxxxx",
      "status": "pending",
      "created_at": "2015-01-20 13:04:45",
      "updated_at": "2015-01-21 13:04:45",
      "image_count" : 2,
      "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url" : "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
      ],
      "data" : {
      }
    },
    {
      "id":111112,
      "validation_type":"receipt",
      "campaign_id":12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id":"xxxxx",
      "status":"valid",
      "store_name":"ACME Pharmacy",
      "receipt_date":"2016-02-16 14:21:10",
      "created_at":"2016-02-11 06:48:23",
      "updated_at":"2016-02-16 14:21:10",
      "image_count":1,
      "images":[
         { "id" : "200", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" }
      ],
      "data":{
      },
      "results":[
        {
          "id" : "111112-1",
          "name" : "3600000001",
          "description" : "example",
          "price" : 1.05,
          "quantity" : 2,
          "points" : 10
        },
        {
          "id" : "111112-2",
          "name" : "3600000002",
          "description" : "example 2",
          "price" : 2.50,
          "quantity" : 1,
          "points" : 10
        }
      ]
    },
    {
      "id":111113,
      "validation_type":"receipt",
      "campaign_id":12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id":"xxxxx",
      "status":"invalid",
      "invalid_code":1,
      "invalid_reason":"We cannot read your receipt clearly. Please make sure to take the picture with ample lighting showing your qualifying purchase.",
      "created_at":"2016-02-11 06:49:23",
      "updated_at":"2016-02-16 14:22:59",
      "image_count":1,
      "images":[
         { "id" : "300", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" }
      ],
      "data":{
      }
    }
  ]
}


The following tables document this array:

Response Attributes for Image Validation

Attribute Type Description
id integer Image Validation ID.
validation_type string Shows validation type: receipt to explicitly specify a receipt capture and validation; image for regular image validation.
campaign_id integer SessionM campaign identifier for the image. Each campaign has a defined set of rules and actions.
campaign_permalink string SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id string Your placement ID. Format: placement_id=your-placement-id.
user_id string SessionM customer identifier.
status string Statuses include: incomplete, pending, valid and invalid. Note that invalid validations include the invalid_code and the invalid_reason keys.
invalid_code integer For a list of invalid image codes, see the table in Invalid Image Codes.
invalid_reason string For a list of invalid image code reasons, see the table in Invalid Image Codes.
created_at string Image validation creation UTC date time.
updated_at string Image validation last updated UTC date time.
image_count integer Used for uploading one image at a time through the /images route.
images array List of image objects attached to the image validation with URLs.
data object Free form hash.
results array For more information on the objects in the results array, see table below.

Response Attributes for Results

Attribute Type Description
id string Image Validation ID and a result identifier combined with a hyphen.
name string UPC / SKU code or product name.
description string Product description.
price float Price payed for the receipt line item.
quantity integer Number of products purchased.
points integer Number of points earned for the receipt line item.

Invalid Image codes

The following table details the codes for invalid images:

Invalid Image Codes

Code Description
0 Unknown
1 Receipt cannot be read clearly
2 Receipt is cropped
3 Receipt submitted twice
4 Receipt submitted outside of campaign dates
5 Image is not a receipt
6 No valid purchases found
7 Purchases are from a non-qualifying store
8 Image cannot be read clearly
9 Image is unrelated to campaign
10 Image submitted twice
11 Image submitted outside of campaign dates
12 Image has no valid purchases found, similar to 6
13 Multiple submissions not allowed for this campaign
14 Required fields missing from the receipt
15 Loyalty card linked to same retailer
16 Award limit reached
17 Image appears to have been altered.
18 Non-participating region

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Promo Code APIs

The Promo Code APIs use Promotion, Codes, Generation and Claims objects to provide programmatic access to a promo code engine in the SessionM Platform, one that can generate promo codes so they can be redeemed by a customer for an incentive. Typically, redeeming a promo code awards the customer with points. Promo codes can enable customer service teams and in-store sales teams to reward customers on the spot for activities such as positive feedback and social media sharing. Customer service teams can use promo codes to mitigate negative customer experiences as well.

Promo codes can be one of two possible types: single- or multi-use. The single-use code can be used only once by a customer. Each code is unique and is generated in large promo code lists via the promo code generation function. After the customer redeems the code, it is deactivated.

The multi-use code can be used by multiple customers. The code is reusable across multiple customers. It does not utilize the promo code generation function.

Promo codes are designed to be redeemed by thousands of customers. Therefore, thousands of promo codes might be disseminated across the customer community being serviced by the platform. The organization, however, can protect itself from the risks associated with an unwieldy number of redemptions by setting caps.

The Promo Code API is a collection of APIs that can be organized into a two distinct groupings: APIs that operate on the promo code list; and, APIs that operate on the promo codes associated with an instance of a promo code list.

This section contains the following discussions:

Promo Code Syntax

Single-use codes are 16 characters long and constituted by the base-31 alphabet:

02345679ABCDEFGHJKLMNPQRSTVWXYZ

Note that the exclusions (1, 8, I, O, U) remove ambiguity for customers trying to read printed codes. For example, the digit "1" might look like the letter "L".

Codes are generated and distributed with uppercase letters. Although, upon entry either uppercase or lowercase are accepted because the values are normalized down to the common storage format prior to lookup.

The makeup of the single-use code is as follows:

Multi-use codes can be of any length <= 64 characters, and made up of any alphanumeric characters. Multi-use codes cannot be 16 characters in length AND consist solely of the single-use promotion code alphabet; this would conflict with the structure of single-use codes.

Promo Codes List API

The Promo Code List API uses Promotion objects to represent promo code lists programmatically. You can invoke these APIs to create or update a list, as well as retrieve an array of promo code lists or the data associated with one in particular.

This API provides the following methods:

Retrieve All Promo Code Lists

Retrieves all promo code lists that utilize promo codes. On success, an object with an array of promo code lists is returned. If this list is empty, there are no lists.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET  /priv/v1/apps/:api_key/promotions
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotions array, which is shown below:

▿ JSON Response

{
    "status": "ok",
    "promotions": [
        {
            "id": 77,
            "name": "My Multi Use Promotion",
            "promo_type": "multi_use",
            "global_entry_cap": 20,
            "points": 10,
            "claim_count": 0,
            "starts_at": "2016-06-06T15:01:20Z",
            "ends_at": "9999-12-31T23:59:59Z",
            "codes_generated": 2,
            "multi_use_codes": [
                "WINBIG1",
                "WINBIG2"
            ]
        },
         {
            "id": 79,
            "name": "My Single Use Promotion",
            "promo_type": "single_use",
            "global_entry_cap": 20,
            "points": 10,
            "claim_count": 0,
            "starts_at": "2016-06-06T15:11:50Z",
            "ends_at": "9999-12-31T23:59:59Z",
            "codes_generated": 2
        }
    ]
}


The following table provides details on the promotions array:

Response Attributes for Promotions

Attribute Type Description
id integer Primary key for promo code list.
name string Human-readable, unique name for promo code list.
promo_type enumeration Type of promo code list: single_use or multi-use.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
points integer Number of points to award when the incentive is points.
claim_count integer Number of successful codes redeemed for the promo code list.
starts_at datetime ISO8601 datetime that promo codes for the promo code list start being accepted.
ends_at datetime ISO8601 datetime that promo codes for the promo code list stop being accepted.
codes_generated integer Number of promo codes generated in the promo code list.
multi_use_codes string array Contains multi-use codes associated with this list. Only available if promo list is of type multi_use
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Specifics on a Promo Code List

Retrieves Promo Code List specifics using the relevant list ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET  /priv/v1/apps/:api_key/promotions/:promotion_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
promotion_id Primary key identifying the promotion.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, which is shown below:

▿ JSON Response

{
  "status": "ok",
  "promotion": {
    "id": 1,
    "name": "My Single Use Promotion",
    "promo_type": "single_use",
    "global_entry_cap": 20,
    "points": 10,
    "claim_count": 0,
    "starts_at": "2016-06-06T14:15:36Z",
    "ends_at": "9999-12-31T23:59:59Z",
    "codes_generated": 0,
    "codes_redeemed": 0,
    "generation_requests": []
  }
}


This object is documented in the following table:

Response Attributes for Promotion

Attribute Type Description
codes_generated integer Number of promo codes generated in the promo code list.
codes_redeemed integer Number of promo codes redeemed in the promo code list.
unique_users_redeeming integer Number of unique customers who have claimed codes.
generation_requests array Promo Code Batch generation requests.
id integer ID of of batch requests to generate new promo codes.
state enumeration Current state of the request. Options include: requested, generating, generated and failed.
email_recipients string Comma-separated list of email addresses to email upon generation of codes.
num_codes integer Number of promo codes requested.
name string Human-readable name for generation request.
created_at datetime ISO8601 datetime that promo code generation request was created.
updated_at datetime ISO8601 datetime that promo code generation request was updated.
promo_type enumeration Type of promo code list: single_use or multi-use. For information on syntax requirements, see the Promo Code Syntax.
points integer Number of points to award when the incentive is points.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
starts_at ISO8601 datetime When promo codes become active. If no value is specified, the list starts immediately. Note that the value for this field must not be in the past and must be less than the value specified for ends_at.
ends_at ISO8601 datetime When promo codes are no longer valid. If no value is specified, codes are valid indefinitely.
claim_count integer Number of successful codes redeemed for the promo code list.
multi_use_codes type Array of strings containing multi-use code(s) associated with this promo code List when it's a multi use code promotion.
organization_id type Foreign key identifier for the organization to which the policy applies.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
BAD_DATA Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a New Promo Code List

Builds a new promo code list. On success, the ID of the newly created promo code list is returned. If this is empty, no promo code lists exist.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/promotions
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, which is shown below:

▿ JSON Request (Single Promo Code List)

{
  "promotion":
  {
    "name": "My Single Use Promotion",
    "promo_type": "single_use",
    "points": 10,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-07-16T17:41:08Z",
    "global_entry_cap": 4
  }
}

▿ JSON Request (Multi Promo Code List)

{
  "promotion":
  {
    "name": "My Multi Use Promotion",
    "promo_type": "multi_use",
    "points": 10,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-07-16T17:41:08Z",
    "global_entry_cap": 4,
    "multi_use_codes": [ "WINBIG" ]
  }
}


This object is documented in the following table:

Request Attributes for Promotion

Attribute Type
Required/Optional
Description
name string
required
Readable, unique name for promo code list.
promo_type enumeration
required
Type of promo code list: single_use or multi-use. For information on syntax requirements, see the Promo Code Syntax
points integer
required
Number of points to award when the incentive is points.
starts_at ISO8601 datetime
optional
When promo codes become active. If no value is specified, the list starts immediately. Note that the value for this field must not be in the past and must be less than the value specified for ends_at.
ends_at ISO8601 datetime
optional
When promo codes are no longer valid. If no value is specified, codes are valid indefinitely.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
multi_use_codes array
required
Only required for multi use promotions. Array of strings containing multi-use code(s) associated with this promo code list.
Response Object

In addition to a status key-value pair, the response object returned by the method contains the ID of the new list, as shown below:

▿ JSON Response

{
  "status": "ok",
  "id": 126
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
promo_type Can't be blank.
promo_type Is not included in the list.
name Can't be blank.
name Has already been taken.
points Is not a number.
points Must be an integer.
points Must be greater than 0.
promotion_multi_use_codes Multi use code(s) must be provided for multi use promotions.
bad_data Invalid date: \"Not-an-ISO-date\".

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Promo Code List

Modifies an existing promo code list.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/promotions/:promotion_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
promotion_id Primary key identifying the promotion.
Request Object

When this method runs, it passes in a request object that contains a promotion object, as shown below:

▿ JSON Request

{
 "promotion":
  {
    "name": "Updated promo code list",
    "global_entry_cap": 3,
    "ends_at": "2016-06-16T17:41:08Z"
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "promotion": {
    "id": 118,
    "name": "Updated promo code list",
    "promo_type": "single_use",
    "points": 10,
    "global_entry_cap": 3,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-06-16T17:41:08Z",
    "claim_count": 125,
    "codes_generated": 10000
  }
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
bad_data No parameters given.
bad_data Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Promo Codes API

The Promo Codes API exposes the platform's functions for managing promo codes programmatically. This API allows you to manage promo codes and their use, or redemption, by customers. You can invoke one to create a batch of single-use promo codes as well as retrieve the codes associated with a particular promo code list. Once issued, you can discover the status of the batch request. In addition, you can use the API to manage an individual promo code, searching for it and claiming it for an incentive.

This API support the following methods:

Create Batch of Single-use Promo Codes for Promo Code List

Generates a batch of promo codes for a single-use promo code list. On success, an ID for the generation request is returned.

By default, requests are capped at 1 million codes. Contact your SessionM representative if you need to raise the cap.

Batch code generation is handled asynchronously. The workflow is as follows:

  1. Send request to generate codes.
  2. Receive HTTP 200.
  3. Recipient polls status endpoint until codes are ready.
  4. Recipient queries get route to retrieve codes.
Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/promotions/:promotion_id/codes
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
promotion_id Primary key identifying the promotion.
Request Object

When this method runs, it passes in a request object that contains a generation object, which is shown below:

▿ JSON Request

{
  "generation":
  {
    "num_codes": 1,
    "email_recipients": ["email@domain.com"],
    "name": "batch1"
  }
}


This object is detailed in the following table:

Request Attributes for Generation

Attribute Type
Required/Optional
Description
num_codes integer
required
Number of promo codes requested.
email_recipients array
required
Array of recipients that are to be notified via email when the batch of promo codes has been successfully generated.
name string
optional
Batch name. Optional field. Length of field limited to 255 characters.

Note that the HTTP_MESSAGE_ID header can be set on the request, and can be used to identify your request later.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a code_generation_request object, which is shown below:

▿ JSON Response

{
  "code_generation_request":
  {
    "id": 1,
    "state": "generated",
    "email_recipients": null,
    "num_codes": 100,
    "created_at": "2016-06-16T17:41:08Z",
    "updated_at": "2016-06-17T17:41:08Z"
  }
}


This object is detailed in the following table:

Response Attributes for Code Generation

Attribute Type Description
id integer ID of of batch requests to generate new promo codes.
state string Current state of the request. Options include: requested, generating, generated and failed.
email_recipients array
required
Array of recipients that are to be notified via email when the batch of promo codes has been successfully generated.
num_codes integer
required
Number of promo codes requested.
created_at ISO8601 datetime When promo code generation request was created.
updated_at ISO8601 datetime When promo code generation request was updated.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
bad_data Can only perform operation on single use promotions.
bad_data Validation failed: Name must be unique.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Promo Codes for Promo Code List

Retrieves a list of all promo codes associated with a promo code list. On success, an array of promo codes is returned along with a status. This method includes endpoint parameters that limit the codes returned by specific generation ID or a message ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/promotions/:promotion_id/codes?<filters>
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
promotion_id Primary key identifying the promotion.
code_generation_request_id Identifier for a generation request for this promo list. It is returned via the generate call. Optional field.
message_id HTTP header set when request is generated. Optional field. Omitting the filter will return all codes from a list.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which contains multiple promo codes, as shown below:

▿ JSON Response

{
  "status": "ok",
  "codes": [
    "CODE_1",
    "CODE_2"
  ]
}
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
unknown_promotion Returned when the caller passes in a promotion_id that is not found in the system.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Status for Promo Code Generation Request

Retrieves a status for the request to generate a batch of promo codes for a promo code list. On success, a status for the promo code generation request is returned.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/promotions/:promotion_id/codes/status/:code_generation_request_id
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
promotion_id Primary key identifying the promotion.
promotion_code_generation_request_id Foreign key to the code generation request.
Request Object

Not applicable.

Response Object

This object contains status and state key-value pairs, as shown below:

▿ JSON Response

{
  "status": "ok",
  "state": "generated"
}


For a description of the response state attribute, see the generation request attributes table for the promotion object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
bad_data Unknown code generation request.
bad_data Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Claim Promo Code

Allows customers to claim a particular promo code using either the ID generated in the platform or the ID generated by an external system.

The code field in the request data is revised accordingly for single- and multi-use codes:

The following conversions are made for only single-use codes:

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/promotions/claims
POST /priv/v1/apps/:api_key/external/users/:external_id/promotions/claims
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

When this method runs, it passes in a request object that contains a claim object, which is shown below:

▿ JSON Request

{
  "claim":
  {
    "code": "P0009BD4TVQXWEH7",
    "audit_data": ""
  }
}


This object is detailed in the following table:

Request Attributes for Claim

Attribute Type
Required/Optional
Description
code string
required
Code being claimed
audit_data string
optional
String of JSON-encoded audit data sent in when the claim was made.
Response Object - Success

The method to claim a promo code can generate a variety of responses indicating success. The sections that follow are dedicated to specific kinds of responses.

In addition to the status value-pair, the method to claim a promo code returns two "child" objects in a successful response:

Those objects are shown below:

▿ JSON Response

{
  "status": "ok",
    "claim": {
      "id": 53,
      "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
      "promotion_id": 7,
      "code_plaintext": "P0009BD4TVQXWEH7",
      "claim_context": {
        "awards": [
          {
            "type": "points",
            "value": 5
          }
        ]
      },
      "audit_data": {}
    },
    "promotion": {
      "id": 7,
      "name": "Test promotion new 5",
      "promo_type": "single_use",
      "global_entry_cap": 9,
      "points": 5,
      "claim_count": 3,
      "starts_at": "2016-05-17T11:33:59Z",
      "ends_at": "2016-06-16T04:00:00Z",
      "codes_generated" : 5
    }
}
Claim Object

The following table documents the claim object.

Response Attributes for Claim

Attribute Type Description
id integer Primary key for the claim.
user_id integer Primary key for the customer claiming the promo code.
promotion_id integer Identifier of the associated promo code list.
code_plaintext string Formatted code for the customer's input.
claim_context object See table below.
audit_data object JSON-encoded audit data sent in when the claim was made. Next, the data represents the promo code list with promotion.
Claim Context Object

This object contains an awards object, which detailed in the following table:

Response Attributes for Awards in Claim Context

Attribute Type Description
type string The award type.
value integer The value to award.
Promotion Object

This method returns a Promo Code List response object. In addition to a status key-value pair, this object contains the promotion object.

Response Object - Failure

The method to claim a promo code can generate a variety of responses indicating failure. The sections that follow are dedicated to specific kinds of error responses when a promo code is claimed.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Claim Error Response Due to Promo Code Not Found

In addition to the status key-value pair, the response object returned when a promo code is not found contains a few other attributes. The number_of_attempts_before_lockout key-value pair is the number of attempts a customer can make before being locked out of the promotion.

The response also includes three "child" objects:

These objects are shown below:

▿ JSON Response (Promo Code Not Found)

{
 "status": "error",
 "errors": {
   "code": "code_not_found",
   "message": "claim code can not be found"
 },
 "lockout_record": {
   "id": 8,
   "event_type": "promo_code",
   "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
   "consecutive_count": 3,
   "cumulative_count": 18,
   "reset_counter": 0
 },
 "lockout_policy": {
   "id": 2,
   "starts_at": "2016-04-11T16:02:03Z",
   "ends_at": "2016-07-11T16:02:03Z",
   "organization_id": 7,
   "type": "promo_code_lockout",
   "consecutive_count": 10,
   "cumulative_count": 30,
   "lockout_duration": 86400
 },
"number_of_attempts_before_lockout": 7
}


The following sections contain tables that provide details on these objects.

Errors Object

Attribute Type Description
code string Error code for the error. Includes:

- code_not_found, which displays if the promo code isn't found.
- user_locked_out, which displays if the customer is locked out.
- user_perm_locked_out, which displays if the customer is permanently locked out.
- cancelled_code, which displays if the code was cancelled by the operator.
- inactive_promotion, which displays if the promotion is inactive.
- claimed_code, which displays if the code is already claimed.
- no_available_cap, which displays if no global entry cap is available.
message string Human readable string useful for API debugging. Refrain from creating any business logic that depends on it; instead, use one of the error codes shown in the row above.

Lockout Record Object

Attribute Type Description
id integer Lockout record ID associated with a customer's lockout.
event_type string Enumeration that defines type of lockout being tracked, promo_code.
user_id string Identifier for customer making the claim or being locked out.
consecutive_count integer Number of lockout-eligible events that have happened in a row for a specific type.
cumulative_count integer Number of lockout-eligible events that occurred all time.
lockout_expires datetime Time at which lockout expires. If customer has hit their all-time lockout, then this value reflects datetime.max.
reset_counter integer Tracks number of times counters have been reset by an administrator.

Lockout Policy Object

Attribute Type Description
id integer Identifier for the customer's lockout policy.
starts_at datetime ISO8601 datetime that lockout policy is effective.
ends_at datetime ISO8601 datetime that lockout policy stops being effective.
organization_id integer Foreign key identifier for the organization to which the policy applies.
type string Type of policy, promo_code_lockout.
consecutive_count integer Number of lockout-eligible events that a customer can do in a row for a specific type before being locked out temporarily.
cumulative_count integer Number of lockout-eligible events that a customer can do before being locked out permanently.
lockout_duration integer Lockout duration in seconds.
Claim Error Response Due to Customer Lockout

Claim error responses due to customer lockouts contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Claim Error Response Due to Customer Lockout Hitting Cumulative Count

Claim error responses due to customer lockout hitting a cumulative count contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

▿ JSON Response (Promo Code Not Found Due to Customer Lockout from Hitting Cumulative Count)

{
  "status": "error",
  "errors": {
    "claim": {
      "promotion_id": "promo list id",
      "user_id": "user id"
      },
      "code": "user_perm_locked_out",
      "message": "user is permanently locked out"
    },
 "lockout_record": {
   "id": 8,
   "event_type": "promo_code",
   "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
   "consecutive_count": 3,
   "cumulative_count": 30,
   "lockout_expires": "9999-01-01T00:00:00Z",
   "reset_counter": 0
 },
 "lockout_policy": {
   "id": 2,
   "starts_at": "2016-04-11T16:02:03Z",
   "ends_at": "2016-07-11T16:02:03Z",
   "organization_id": 7,
   "type" : "promo_code_lockout",
   "consecutive_count": 10,
   "cumulative_count": 30,
   "lockout_duration": 86400
 },
"number_of_attempts_before_lockout": 0
}
Claim Error Response for a Cancelled Code

Claim error responses for a cancelled code contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

▿ JSON Response (Cancelled Code)

{
   "status": "error",
   "errors":
   {
      "code": "cancelled_code",
      "message": "Code cancelled by operator"
    }
}
Claim Error Response for an Inactive Promotion

Claim error responses for an inactive promotion contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

▿ JSON Response (Claim Error for Inactive Promotion)

 {
  "status": "error",
  "errors": {
   "code": "inactive_promotion",
   "message": "inactive promotion"
   }
 }
Claim Error Response for Already Claimed Code

Claim error responses for already claimed codes contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

▿ JSON Response (Claim Error for Already Claimed Code)

{
  "status": "error",
  "errors": {
  "code": "claimed_code",
  "message": "code is already claimed"
  }
}
Claim Error Response for No Available Global Entry Cap

Claim error responses for no available global entry cap contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

▿ JSON Response (Claim Error for No Available Global Entry Cap)

{
  "status": "error",
  "errors": {
  "code": "no_available_cap",
  "message": "no available cap"
  }
}

Retrieve Invalid Promo Codes Claimed by Customer

This method retrieves promo codes that were deemed invalid when claimed by a customer. When successful, the invalid codes are returned along with their timestamp and reason for being invalid.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/promotions/claims/errors
GET /priv/v1/apps/:api_key/external/users/:external_id/promotions/claims/errors
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which is shown below:

▿ JSON Response

{
 "codes":
 [
    { "code": "68723695",
      "created_at": "2016-04-21T16:02:03Z",
      "error_reason": "invalid"
    }
 ]
}


This array is detailed in the following table:

Response Attributes for Codes

Attribute Type Description
code string Invalid promo code claimed by customer.
created_at datetime ISO8601 datetime that the error occurred.
error_reason string Obtained from the enumeration for the promotion_code_claim_error class. Enumeration values for the error reason include. These values include invalid, not_active, cancelled, and claimed.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Search Promo Codes by Criteria

Filters for and retrieves claimed promo codes based on customer ID or external ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/promotions/claims/?filter criteria
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform making the claim.
external_id Identifier for a customer (claimant) in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which is shown below:

▿ JSON Response (Promo Code Found)

{
  "codes":
  [
    {
      "code": 923481653,
      "type": "single_use",
      "claim": {
         "claimdatetime": "2016-10-07T15:48:28Z",
         "user_id": "4642b4-142-1e6-9130-09ad14633",
         "external_id": "7642b4-09ad149935",
         "audit_data": "\"\"",
         "claim_details": "prize details",
         "promotion_id": "1",
         "promotion_name": "grand prize"
       }
    }
  ]
}


This array is detailed in the following tables:

Response Attributes for Codes

Attribute Type Description
code string Promo code searched for by the customer.
type string Enumeration for single-use or multi-use promo code.
claim object Empty if none exist. For more information, see table below.

Response Attributes for Claim

Attribute Type Description
claimdatetime datetime ISO8601 formatted timestamp for the claimed code.
user_id string ID of the claimant.
external_id string ID of the claimant if the customer has an identifier on an external system.
audit_data object JSON-encoded audit data sent in at the time of the claim.
claim_details string Description of what was claimed.
promotion_id integer ID of the associated promotion.
promotion_name string Name of the associated promotion.

If no codes are found, then the returned array is empty. If the code is a multi-use code and the search is by code only, no claim data is returned since the thousands of claimers could exist.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Search by Promo Code

Filters for and retrieves data about a specific promo code.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/promotions/codes?code=<code>
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
code Specified promo code.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains several attributes, some of which are other "child" objects, as shown below:

▿ JSON Response (Unclaimed Valid Promo Code Found in Search)

{
   "cancellation":null,
   "claim":null,
   "multi_use":false,
   "promotion":{
      "claim_count":0,
      "codes_generated":100,
      "codes_redeemed":0,
      "ends_at":"9999-12-31T23:59:59Z",
      "generation_requests":[
         {
            "created_at":"2016-07-27T16:24:49Z",
            "email_recipients":"machism2007@outlook.com",
            "id":1,
            "name":"First Batch of Codes",
            "num_codes":100,
            "state":"generated",
            "updated_at":"2016-07-27T16:27:02Z"
         }
      ],
      "id":199,
      "name":"Latest Single Use Promotion",
      "points":10,
      "promo_type":"single_use",
      "starts_at":"2016-07-26T19:03:41Z",
      "unique_users_redeeming":0
   },
   "status":"ok"
}

▿ JSON Response (Claimed Valid Promo Code Found in Search)

{
   "cancellation":null,
   "claim":{
      "audit_data":"\"1\"",
      "claim_context":{
         "awards":[
            {
               "type":"points",
               "value":25
            }
         ]
      },
      "code_plaintext":"P007G4RBHXQ073JW",
      "created_at":"2016-07-27T22:44:05Z",
      "id":17,
      "promotion_id":200,
      "user_id":"0f8691fc-43a6-11e6-9510-2cee2933ac55"
   },
   "multi_use":false,
   "promotion":{
      "claim_count":1,
      "codes_generated":50,
      "codes_redeemed":1,
      "ends_at":"9999-12-31T23:59:59Z",
      "generation_requests":[
         {
            "created_at":"2016-07-27T22:38:02Z",
            "email_recipients":null,
            "id":1,
            "name":"50 codes",
            "num_codes":50,
            "state":"generated",
            "updated_at":"2016-07-27T22:38:20Z"
         }
      ],
      "id":200,
      "name":"Promo Code List 1000",
      "points":25,
      "promo_type":"single_use",
      "starts_at":"2016-07-27T22:37:29Z",
      "unique_users_redeeming":1
   },
   "status":"ok"
}


The following table provides details on the response object:

Response Attributes for Promo Code

Attribute Type Description
cancellation object Serialized cancellation model as defined by API to cancel a code; null if it has not yet been cancelled. For more information, see Cancel a Promo Code.
claim object Empty if none exist. Otherwise, if successful, the claim is represented with the data below. For more information on the claim object, see its related discussion in Successful Responses for Claiming a Promo Code.
multi_use boolean If the promo code can be used multiple times.
promotion object All the base information returned by the API that retrieves specifics for a promo code list. For more information on this object, see the table detailing the promotion object.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid_code Promo code found in search is invalid.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Cancel Promo Code

Marks a promo code as operator cancelled, which means it is no longer available. It provides an effective way of handling lost or stolen codes. Only single-use codes can be cancelled.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/promotions/codes
Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
Request Object

When this method runs, it passes in a request object that contains a codes array, which is shown below:

▿ JSON Request

{
  "codes": ["SOME_VALID_CODE", "SOME_INVALID_CODE"]
}


The array is detailed in the following table:

Request Attributes for Codes

Attribute Type
Required/Optional
Description
codes array
required
Array of codes to cancel.
Response Object

In addition to a status key-value pair, the response object returned by the method contains the attributes shown below:

▿ JSON Response

{
"codes_cancelled": ["SOME_VALID_CODE"],
"codes_failed":
    [
      {
        "code" : "SOME_INVALID_CODE",
        "reason" : "code could not be found"
      }
    ]
}


The response object is detailed in the following table:

Response Attributes for Cancelling a Promo Code

Attribute Type Description
codes_cancelled array Promo codes marked as cancelled.
codes_failed object Promo codes unable to be cancelled. Object contains the code that failed as well as the reason as to why it failed.
Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found Customer not found.
limiter_type_invalid Invalid limiter_type specified.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Advanced

The SessionM Platform offers a set of APIs and procedures that support some complex and generally less common implementation goals. This section contains an evolving collection of APIs and procedures for development efforts that may exceed the standard functions expressed in the platform's core APIs. Sections include:

Model API

This API uses Model objects to facilitate the display of attributes for a specified model. Each model contains attributes that allow third-party systems to retrieve models and model attributes within the platform. These models can be fully developed in an external system and then passed to the platform. It is also possible to configure models natively within the platform and then allow any 3rd party system to retrieve or modify those models. Currently models are limited to 200 attributes per single model.

The SessionM has implemented a model called user_profiles, which expresses data for a customers' custom profiles. This, however, is only one implementation. Ultimately, the Model API can be used to create models that represent any type of data.

This API provides a method that retrieves all the current attributes associated with a customer model.

Retrieve a Customer Model

Returns a single customer model, based on the provided model name. The model returned contains the associated custom profile.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/models/:model_name

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
model_name Identifier for an organization customer model in the SessionM Platform. For example: GET /v1/apps/:api_key/models/user_profiles. This is the default customer model for the SessionM Platform. An organization may have multiple models.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a model object, which is shown below:

▿ JSON Response

{
    "model": {
        "attributes": {
            "nickname": {
                "filters": [
                    "Downcase"
                ],
                "length": {
                    "maximum": 20,
                    "minimum": 2
                },
                "list": false,
                "type": "string"
            },
            "total_amount": {
                "list": false,
                "numericality": {
                    "greater_than_or_equal_to": 0
                },
                "type": "integer"
            }
        },
        "name": "user_profiles",
        "request_key": "user_profile",
        "version": "a79dd212-8b44-11e6-9a2f-322cc1d29f66"
    },
    "status": "ok"
}


The following table documents this object:

Response Attributes for Model

Attribute Type Description
attributes object Contains two "child" objects, nickname and total_amount. Each of these objects are client-defined custom attributes. For information on the rules governing attribute definition, see Attribute Definition Characteristics.
name string Name of the customer model.
request_key string Identifier for the associated request object.
version string Version of the customer model.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
not_found Indicates that the specified customer model was not found in the system.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Lockout API

Lockouts are used to keep running tallies of invalid attempts and lock customers out of various event types. Currently, the SessionM Platform supports lockouts for promotion code entry. Organizations can configure a lockout policy that dictates how many invalid promotion codes a customer can enter before they are locked out from entering any more codes. Lockout policies are configured in the platform using the SessionM Administration Portal. For more information, talk to your SessionM integration engineer.

The characteristics and constraints that constitute a lockout are configured in lockout policies. In addition to type and the datetimes that establish when it is in effect, policies contain a few other kinds of metadata about a customer's lockouts, including:

Lockout policies are one implementation of the policy object. For example, for promo code lockout policies, the type is promo_code_lockout.

This API supports the following methods:

Retrieve a Lockout Policy and Lockout Data for a Customer

This method retrieves an existing lockout record for a customer; if none exists then the customer has no lockout record. A value for the lockout type enumeration is required.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET  /priv/v1/apps/:api_key/users/:user_id/lockout?event_type=<type>
GET  /priv/v1/apps/:api_key/external/users/:external_id/lockout?event_type=<type>

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
event_type If the event_type is "promo_code", retrieve a lockout policy in support of promo codes. If there is no active policy, then the policy node’s value will be null; if the customer does not have a currently active lockout of type , then the returned structure’s customer node's value will be null.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains two objects. They include:

These objects are shown below:

▿ JSON Response

{
 "policy":
 {
    "id": 8,
    "starts_at": "2016-08-27T22:37:29Z",
    "ends_at": "2016-09-27T22:37:29Z",
    "organization_id": 3627,
    "type": "promo_code_lockout",
    "consecutive_count" : 1000,
    "cumulative_count" : 30000,
    "lockout_duration" : 86400
  },
  "player":
  {
    "id" : 8776,
    "event_type": "promo code",
    "user_id" : "83003",
    "consecutive_count" : 1000,
    "cumulative_count" : 25000,
    "lockout_expires" : "2016-09-27T22:37:29Z",
    "reset_counter" : 1
 }
}
Policy Object

The table below provides details on the policy object. Some of the attributes in the table apply only to lockout policies, while others apply only to limiter policies.

Response Attributes for Policy

Attribute Type Description
id integer Lockout or limiter policy ID.
starts_at datetime ISO8601 formatted datetime at which the policy becomes effective.
ends_at datetime ISO8601 formatted datetime at which the policy stops being in effect.
created_at datetime ISO8601 formatted datetime at which the policy was created.
updated_at datetime ISO8601 formatted datetime at which the policy was updated.
organization_id integer Foreign key for organization.id.
type string Enumeration that describes policy types, such as promo_code_lockout.
consecutive_count integer Number of invalid codes that have been entered consecutively since the last lockout period expired.
cumulative_count integer The number of cumulative event types done by the customer.
lockout_duration integer Duration of lockout period.
data object Object containing specific policy configuration. See next row for more information.
data["quantums"] enumeration Enumeration that provides values that correspond to periods of time, including: weekly, monthly and yearly.
Player Object

The following table provides details on the player object:

Response Attributes for Player

Attribute Type Description
id integer Lockout ID.
event_type string Enumeration that defines the type of lockout being tracked, such as promo code.
user_id string ID of the customer being locked out.
consecutive_count integer Number of invalid codes that have been entered consecutively since the last lockout period expired.
cumulative_count integer The number of cumulative event types done by the customer.
lockout_expires datetime ISO8601 formatted datetime at which the lockout expires.
reset_counter integer Number of times lockout has been reset.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
bad_data Error for an invalid customer if the customer is invalid.
bad_data Error for an invalid event type if event type is invalid.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Reset a Lockout Counter for a Customer

This method resets a lockout counter for a customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST  /priv/v1/apps/:api_key/users/:user_id/lockout/reset
POST  /priv/v1/apps/:api_key/external/users/:external_id/lockout/reset

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a lockout object, which is shown below:

▿ JSON Request

{
  "lockout":
  {
    "event_type": "promo_code"
  }
}


This object is detailed in the following table:

Request Attributes for Lockout Reset

Attribute Type
Required/Optional
Description
event_type string
required
Enumeration for lockout types. Possible values include the string, promo code.

Response Object

This method returns a status key-value pair, as shown below:

▿ JSON Response

{
  "status": "ok"
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
bad_data Error for an invalid customer if the customer is invalid.
bad_data Error for an invalid event type if event type is invalid.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Limiter API

The Limiter API allows you to keep running tallies of a customer’s events over periods of time. For promotion codes, limiters limit the number of codes that a customer can enter within a quantum (weekly, monthly, or yearly time period).

Limiters go hand in hand with a policy that defines how to govern the event in question. The policy defines the configuration that drives the implementation of the limiter. The limiter is the real-time counter of the customer’s actions with respect to the policy definition.

The Limiter API is designed to retrieve existing limiter policies. These policies are configured in the platform using the SessionM Administration Portal. For more information, talk to your SessionM integration engineer.

This API offers a method to implement the retrieval of limiter policies and customer specific policy data.

Retrieve Limiter Policies and Customer Specific Policy Data

This method retrieves current active limiter policies policy data defined for specific customers based on their user_id or external_id.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/limiters?limiter_type=<type>
GET /priv/v1/apps/:api_key/external/users/:external_id/limiters?limiter_type=<type>

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
limiter_type Filter that retrieves a limiter policy in support of lockouts associated with promo codes. Current valid values for limiter_type include promotion_code_claim.

For example: limiter_type=promotion_code_claim

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains two objects. They include:

These objects are shown below:

▿ JSON Response

{
  "policy" :
  {
    "starts_at" : "2016-12-06 16:00:00",
    "ends_at" : "2016-12-06 16:00:00",
    "created_at" : "2016-12-06 16:00:00",
    "updated_at" : "2016-12-07 16:00:00",
    "data" :
    {
      "quantums" :
      {
        "weekly": 2
      }
    }
  },
  "player_limiters" :
  [
  {
    "id" : 4,
    "limiter_type" : "promotion_code_claim",
    "quantum" : "weekly",
    "starts_at": "2016-12-06 16:00:00",
    "ends_at" : "2016-12-16 16:00:00",
    "counter" : 6,
    "created_at" : "2016-12-06 16:00:00",
    "updated_at" : "2016-12-07 16:00:00"
  }
  ]
}
Policy Object

For more information see Policy Object.

Player Limiters Object

The following table provides details on the player_limiters object:

Response Attributes for Player Limiters

Attribute Type Description
id integer ID of the customer that is performing events.
limiter_type enumeration Enumeration that provides types for limiter policies, including promotion_code_claim.
quantum enumeration Enumeration that provides values that correspond to periods of time, including: weekly, monthly and yearly.
starts_at datetime ISO8601 formatted datetime at which the limiter policy becomes effective.
ends_at datetime ISO8601 formatted datetime at which the limiter policy is no longer effective.
counter integer Unique index on player_id, org_id, limiter_type and quantum.
created_at datetime ISO8601 formatted datetime at which the limiter policy was created.
updated_at datetime ISO8601 formatted datetime at which the limiter policy was updated.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
user_not_found Customer not found for client-specific limiter policy data.
limiter_type_invalid Limiter type specified is invalid.

If there is no active policy, then the policy field's value will be null. Furthermore, if there is no active policy, then the customer node will also be null, regardless of whether there is active customer data. This could happen if, for example, the policy expires mid-quantum. If there is no active customer record, then the customer node's value will be null.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Encrypting Requests

In the course of developing server-to-server solutions, it may be necessary to encrypt the contents of an HTTPS request. Although requests are encrypted via HTTPS when they are in flight, you can also encrypt them in storage. Doing so creates a kind of safebox for the request and its payload, ensuring that you alone can access it at a subsequent time.

For example, you may want to store a log file on a server without exposing its contents to that server. That same encrypted log file can be replicated on other servers, making it more resistant to server or network failure, or it could be downloaded by clients, making it available offline. In all cases, the contents of the file are not exposed.

This document provides a basic understanding of how to use HTTP content-coding in a message header to encrypt the body (message payload) of an HTTP request. It reflects the methodology detailed in the Internet-Draft Encrypted Content-Encoding for HTTP, which is a working document of the Internet Engineering Task Force (IETF).

Sample Request

Review the sample request in this section to understand how to code the request header. The most important parameters used to encrypt the body of the request include:

▿ Sample Request

POST /quotes HTTP/1.1
Content-Encoding: aes-256-cfb
Encryption: keyid="key1"; salt="Zlx7Drxdhji39P4IIrin0Q"
Crypto-Key: keyid="key1"; aes-256-cfb="TV0tg787F8xGAcXJ0hhdu6430QAdloY7khG2lllWFTI"

pP3dbF//eBI3V9y1vs50EGNL1qH3g9UwfUcxwEs/mg4qDOwkdKA3c9q/dehJj6jclhd7


The actual decrypted body of the request is "You can't win a game if you don't score any points."

Note: The body of this request is base64 encoded, and the body of the Crypto-Key header is for testing purposes only.

Encryption Procedure

To encrypt a request:

  1. Produce a unique key to encrypt the request. For example: shared_secure_key = urlsafe_base64_decode "TV0tg787F8xGAcXJ0hhdu6430QAdloY7khG2lllWFT" salt = urlsafe_base64_decode "Zlx7Drxdhji39P4IIrin0Q" pseudo_random_key = sha256_hmac(salt, shared_secure_key)

  2. You can add a context for an additional security measure such as a shared salt which would protect the request data further.

  3. With the generated key, encode the body of the request. For example: content_encoding_key = sha256_hmac(pseudo_random_key, "Content-Encoding: aes-256-cfb" + 0x00 + context + 0x01)

  4. Set the initialization vector. For example: nonce = sha256_hmac(pseudo_random_key, "Content-Encoding: nonce" + 0x00 + context + 0x01).slice(0, 16) Note: The nonce for each record is a 16 octet (128 bit) value produced from the record sequence number and a value derived from the input keying material.

  5. Now encrypt the request body using the key, iv and payload parameters. For example: encrypted_body = aes_256_cfb_encrypt(content_encoding_key, nonce, "You can't win a game if you don't score any points.")

  6. The request body can also be decrypted via the key, iv and payload parameters. For example: decoded_body = aes_256_cfb_decrypt(content_encoding_key, nonce, base64_decode("pP3dbF//eBI3V9y1vs50EGNL1qH3g9UwfUcxwEs/mg4qDOwkdKA3c9q/dehJj6jclhd7"))

For more information on encrypting requests, please consult your Customer Success contact.

Deprecated APIs

While still supported in select instances, the following APIs have been deprecated in favor of newer API versions or because support for the respective products is ending soon. Unless explicitly instructed by the SessionM Integration team, use the recommended alternative APIs indicated below or contact your SessionM representative with questions.

Orders API

Order objects are closely tied to rewards. More specifically, they are rewards that have been redeemed by a customer. This API allows a third-party system to access orders for a specific customer. In addition, it supports placing an order and retrieving details of previous orders.

When an order is placed, it is initially in a "pending" state. From that point, conditions can be configured for the review of the order or it can be automatically approved without any review.

Once placed, an order reduces the customer's balance. The platform performs validations to determine whether or not the customer is qualified to make the order. It also ensures that there is enough inventory to satisfy the order, and that the IP address is not fraudulent.

Orders can fire emails automatically to whoever is engaged in the order redemption for purposes such as sending out gift card codes. All of the details associated with an order can be reviewed by a managed service, which can generate reports and also handle the requisite fraud tracking and prevention responsibilities. Note that order histories for customers are preserved indefinitely by SessionM.

When customers redeem physical merchandise, the request object passed in with the create method can specify a shipping address. Since shipping addresses associated with orders are free form, the platform performs the requisite validation logic to ensure the address is legitimate.

This API provides the following methods:

Create an Order for a Reward

Builds a new order for a reward.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/offers/:offer_id/orders
POST /priv/v1/apps/:api_key/external/users/:external_id/offers/:offer_id/orders

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
offer_id Identifier for reward tied to order.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains several attributes, including two "child" objects (shipping_address and challenge):

▿ JSON Request

{
  "order": {
    "quantity": 1,
    "email": "example@test.com",
    "ip": "127.0.0.1",
    "shipping_address" : {
      "addressee" : "Mr. Tim O'Brian",
      "street1" : "215 Hanover St.",
      "street2" : "Suite 100",
      "city" : "Boston",
      "state_province" : "MA",
      "country" : "US",
      "postal_code" : "01902"
    },
    "challenge" : {
      "id": 111111
    }
  }
}


These objects are detailed in the following tables:

Request Attributes for Order

Attribute Type
Required/Optional
Description
quantity integer
optional
Defaults to 1.
email string
optional
Fulfillment email. Defaults to the current customer's email address. Data is encrypted for storage on the disk.
ip string
optional
Used for tracking order origins for fraud detection.
shipping_address object
optional
Free form address object.
challenge object
optional
For more information, see the table below.
status string
optional
Order status.

Request Attributes for Challenge

Attribute Type
Required/Optional
Description
id integer
required
Skills test challenge ID. Required only for Canadian contests

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "order": {
    "id": 111111,
    "offer_id": 2,
    "user" : {
      "id":"xxxxx",
      "available_points":"0"
    },
    "quantity": 1,
    "points": 100,
    "status": "pending_approval",
    "created_at": "2015-01-20 13:04:45",
    "name": "Electronic Giftcard",
    "logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
    "description": "Used at electronic.com",
    "shipping_address" : {
      "addressee" : "Mr. Tim O'Brian",
      "street1" : "215 Hanover St.",
      "street2" : "Suite 100",
      "city" : "Boston",
      "state_province" : "MA",
      "country" : "US",
      "postal_code" : "01902"
    }
  }
}


The following table documents this object:

Response Attributes for Order

Attribute Type Description
id integer Order ID.
offer_id integer Reward ID.
user_id string Customer ID.
user object For more information, see the table below.
quantity integer Order quantity.
points integer Total cost in points.
status string Order status: pending_approval, approved, rejected.
created_at string Order creation time in UTC.
name string Reward name.
logo string Reward logo URL.
description string Reward description.
offer_type string Reward type. Sample values include: prize, reward, deal, coupon, instant reward, participation reward, balance transfer, contest entries, benefit, trigger and redemption.
external_id string Order external ID.
shipping address object Free form shipping address if passed in.

Response Attributes for User

Attribute Type
Required/Optional
Description
id string SessionM customer identifier.
available_points integer Customer's current points balance, which can be utilized for the specified order. Displays when the enable_mpoints_info_in_users_api setting is enabled, which is accessed via the SessionM Admin Portal. For more information, consult your Customer Success contact.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid_api_key The API key sent in cannot be found.
user_not_found The customer ID sent in cannot be found.
requires_registered_user The customer ID sent in is not registered.
offer_not_available The reward is not available.
missing_data Required parameter.
challenge_not_found A challenge required by a Canadian contest is required.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Orders for a Customer

Retrieves all of the orders associated with a specified customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/orders
GET /priv/v1/apps/:api_key/external/users/:external_id/orders

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
limit Defaults to 50.
page Defaults to 1.
between Find all orders between these dates; comma-separated.
before Find all orders before this date.
after Find all orders before this date.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an orders array, which can comprise multiple objects, as shown below:

▿ JSON Response

{
  "orders": [
    {
      "id": 111111,
      "offer_id": 2,
      "user_id": "xxxxx",
      "quantity": 1,
      "points": 100,
      "status": "pending_approval",
      "created_at": "2015-01-20 13:04:45",
      "name": "Electronic Giftcard",
      "logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
      "description": "Used at electronic.com",
      "shipping_address" : {
        "addressee" : "Mr. Tim O'Brian",
        "street1" : "215 Hanover St.",
        "street2" : "Suite 100",
        "city" : "Boston",
        "state_province" : "MA",
        "country" : "US",
        "postal_code" : "01902"
      }
    }
  ]
}


For more information, see the order object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve an Order for a Customer

Retrieves an order associated with a specified customer.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/orders/:order_id
GET /priv/v1/apps/:api_key/external/users/:external_id/orders/:order_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
order_id Identifier for the order.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:

▿ JSON Response

{
  "order": {
    "id": 111111,
    "offer_id": 2,
    "user_id": "xxxxx",
    "quantity": 1,
    "points": 100,
    "status": "approved",
    "created_at": "2015-01-20 13:04:45",
    "name": "Electronic Giftcard",
    "logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
    "description": "Used at electronic.com",
    "shipping_address" : {
      "addressee" : "Mr. Tim O'Brian",
      "street1" : "215 Hanover St.",
      "street2" : "Suite 100",
      "city" : "Boston",
      "state_province" : "MA",
      "country" : "US",
      "postal_code" : "01902"
    }
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Update an Order Status

Updates an existing order status.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/orders/:order_id
POST /priv/v1/apps/:api_key/external/orders/:external_order_id
PUT /priv/v1/apps/:api_key/orders/:order_id
PUT /priv/v1/apps/:api_key/external/orders/:external_order_id

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
order_id Identifier for the order.
external_order_id Identifier for order's external ID.

Request Object

When this method runs, it passes in a request object that contains an order object, as shown below:

▿ JSON Request

{
  "order":{
    "status": "approved"
  }
}

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "order": {
    "id": 1,
    "user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
    "offer_id": 1,
    "quantity": 1,
    "points": 6000,
    "status": "approved",
    "created_at": "2015-01-20 13:04:45",
    "name": "$5 Amazon Gift Card",
    "logo": "http://localhost:3001/assets/01/1/13/5amazon.png",
    "description": "Amazon Gift Cards never expire and can be redeemed towards millions of items at Amazon stores and amazon.com",
    "offer_type": "prize",
    "external_id": "external1"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
invalid_api_key The API key sent in cannot be found.
invalid_request_order_status The status of the invalid request order.
invalid_order_status The status of the invalid order.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Points API

Points objects track the chronological history of a customer's points-related transactions and support the addition or removal of points for a customer account balance.

The API provides the following methods:

Add or Remove Points for a Customer Account

Adds, or "comps," points to a customer account as well as removes them. This method also updates the existing points balance.

Note that adding points requires that the points attribute within the request object is set to a positive integer; conversely, if points is set to a negative integer, the method removes points from the account balance.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/:api_version/apps/:api_key/users/:user_id/points

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_version Internal parameter that supports API versioning.
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.

Request Object

When this method runs, it passes in a request object that contains a transaction object, as shown below:

▿ JSON Request

{
  "transaction": {
      "points": 10,
      "type": "survey",
      "model_id": 10,
      "id": "8a8ff754-9994-11e7-9ab2-8efa4370fd7e",
      "user_id": "8a8ff754-9994-11e7-9ab2-8efa4370fd7e",
      "campaign_id": 23,
      "origin": "home_page",
      "source": "mpoints",
      "free_form": "first_survey"
  }
}


This object is detailed in the following table:

Request Attributes for Transaction

Attribute Type
Required/Optional
Description
points integer
required
Number of points being added to or removed from the user account; a positive integer adds points while a negative number removes them.
type string
required
Type of transaction, defined by the endpoint consumer.
model_id integer
required
Type identifier for transaction.
id string
required
Identifier for the transaction.
user_id string
required
Identifier of user.
campaign_id integer
required
Identifier of campaign associated with transaction.
origin string
required
Free form tracking identifier for origin of transaction.
source string
required
Free form tracking identifier for source of transaction.
free_form string
required
Free form tracking information.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object, as shown below:

▿ JSON Response

{
  "status": "ok",
  "user": {
    "id": "6a30816c-9995-11e7-86c4-d4f84370fd7e",
    "available_points": 10
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
missing_data No transaction data.
missing_data No points to add or remove.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Points Transactions for a Customer

Retrieves points transactions for a customer. Maintained in reverse order - most recent first - this API records the points as credits (upon earning points) and as debits (upon redeeming points). Each line item in the record is expressed as a running balance. Note that when a customer incurs a deficit of points, the system awards "negative" points to the customer, ensuring that the appropriate balance is expressed.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id/points/transactions
GET /priv/v1/apps/:api_key/external/users/:external_id/points/transactions

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id Internal identifier for the customer within the SessionM Platform.
external_id Identifier for a customer in an external system integrating with the SessionM Platform.
start_date Start date for period of time that batch of transactions occurred. Optional attribute. Defaults to now. For example, in compliance with ISO 8601/UTC standards: 2016-02-02T17:08:29Z.
end_date End date for period of time that batch of transactions occurred. Optional attribute. Defaults to start_date - 1 month. For example, in compliance with ISO 8601/UTC standards: 2016-02-02T17:08:29Z.
limit Optional attribute that specifies the maximum number of transactions allowed. Defaults to 1000; maximum of 1000.
cursor Handles transactions that exceed limit specified in request. Optional attribute. Normally set to null in a request. Non-null value for cursor in response indicates more transactions to retrieve. This value can be included in a subsequent request to retrieve remaining transactions. null returned for cursor when no more transactions remain.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a cursor attribute along with a transactions object, as shown below:

▿ JSON Response (Success)

{
    "status": "ok",
    "cursor": "123a04a0-c035-11e5-91d3-a6f8eb8b17f8",
    "transactions": [
    {
        "date": "2018-01-19T20:14:17.290Z",
        "description": "20000ptscapCampaignTestA EN-US",
        "record_id": "2-1518",
        "record_model_type_id": 2,
        "record_model_id": 1518,
        "transaction": "credit",
        "source": "achievement",
        "type": "achievement",
        "transaction_id": "79",
        "transaction_type": "receipt",
        "transaction_payload": null,
        "points": 4000,
        "balance": 48000
    },
    {
        "date": "2018-01-19T20:43:10.975Z",
        "description": "achievement_name_here",
        "record_id": "2-1558",
        "record_model_type_id": 2,
        "record_model_id": 1558,
        "transaction": "credit",
        "source": "achievement",
        "type": "achievement",
        "transaction_id": "991230000011",
        "transaction_type": "purchase",
        "transaction_payload":
        {
           "this_is_an_example": "hello"
        },
        "points": 50,
        "balance": 50
    }]
}

▿ JSON Response (Error)

{
  "status": "error",
  "errors": {
    "base": "failed",
    "message": "bad start date"
  },
  "transactions": null
}


For more information on cursor, see its row in the Endpoint Parameters table above.

The following table details the transactions object:

Response Attributes for Points Transactions

Attribute Type Description
date string Timestamp for the transaction.
description string Reflects the name of the behavior or campaign associated with the points.
record_id string Unique record identifier for the transaction.
record_model_type_id integer Identifier for the model type of the transaction record.
record_model_id integer Identifier for the model of the transaction record.
transaction string Type of transaction: credit or debit.
source string Source of points awarded in transaction. Possible values include: achievement, contest, sponsor, merchant_rewards, enterprise, comp, used and expired.
type string Type of points awarded in transaction. Possible values include: donation, sweepstakes, merchandise, digital, digital, physical and receipt.
transaction_id string Identifier for transaction. For example, receipt capture ID or purchase event ID.
transaction_type string (or null) Type of transaction. For example, receipt or purchase.
transaction_payload object (or null) Payload of data associated with transaction.
points integer Points credited or debited.
balance integer Points balance after transaction.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
failed Bad start date.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Tiers API

Tiers objects support the retrieval of a variety of tier-related data, including:

This API provides the following methods:

Retrieve All Tiers

Retrieves data associated with all tiers defined for all tier systems defined for an organization.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/tiers

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a tiers array, which is shown below:

▿ JSON Response

{
  "status": "ok",
  "tiers": [
    {
      "id": 2,
      "name": "bronze",
      "identifier": "bronze",
      "next_tier_id": 3,
      "required_num_days_in_tier": 10,
      "required_points": 500,
      "required_application_achievement_ids": "1,2\n",
      "required_num_achievements": 3,
      "max_inactive_days": 10,
      "required_application_achievement_id": 1,
      "num_days_to_earn_required_achievement": 50,
      "required_sponsor_points": 10,
      "multiplier": "1.0",
      "tier_system_id": 2,
      "maintenance_required_points": 100
    },
    {
      "id": 3,
      "name": "Silver",
      "identifier": "silver",
      "next_tier_id": 4,
      "required_num_days_in_tier": 2,
      "required_points": 1000,
      "required_application_achievement_ids": "3,4\n",
      "required_num_achievements": 4,
      "max_inactive_days": 5,
      "required_application_achievement_id": 1,
      "num_days_to_earn_required_achievement": 20,
      "required_sponsor_points": 4,
      "multiplier": "10.0",
      "tier_system_id": 2,
      "maintenance_required_points": 200
    }
  ]
}


The array is detailed in the following table:

Response Attributes for Tiers

Attribute Type Description
id integer ID for current tier.
name string Name of the tier.
identifier string Descriptive identifier for tier.
next_tier_id integer ID for tier that is available above current tier.
required_num_days_in_tier integer Number of days required to achieve a particular tier status level.
required_points integer Number of points required to achieve a particular tier status level.
required_application_achievement_ids string Identifiers for multiple application achievements required to qualify for tier.
required_num_achievements integer Number of achievements required to qualify for a tier.
max_inactive_days integer Number of days customer can remain inactive before tier status level is revoked.
required_application_achievement_id integer Identifier for single application achievement required to qualify for tier.
num_days_to_earn_required_achievement integer Number of days required to earn achievement.
required_sponsor_points integer Number of points required for a sponsor to qualify for a tier.
multiplier string Factor that multiplies points per tier status level.
tier_system_id integer ID of the tier system associated with the current tier.
maintenance_required_points integer Minimum points required to maintain current tier level status.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve All Tier Systems

Retrieves data associated with all tier systems defined for an organization. Note that this system level metadata - such as settings that reset and activate a tier system - is different than the data returned for a particular tier within a system.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/tier_systems

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains a tier_systems array, which is shown below:

▿ JSON Response

{
  "status": "ok",
  "tier_systems": [
    {
      "id": 2,
      "name": "1",
      "external_id": "t1",
      "active": true,
      "reset_at": "2017-05-27T04:00:00Z",
      "reset_interval": "yearly",
      "last_reset_at": "2017-05-10T20:10:33Z"
    },
    {
      "id": 1,
      "name": "test1",
      "external_id": "test1",
      "active": true,
      "reset_at": "2017-05-27T04:00:00Z",
      "reset_interval": "montly",
      "last_reset_at": "2017-05-10T20:09:53Z"
    }
  ]
}


This array is detailed in the following table:

Response Attributes for Tier Systems

Attribute Type Description
id integer ID for current tier system.
name string Name of current tier system.
external_id string External ID associated with current tier system.
active boolean Determines whether tier system is active (true) or inactive (false).
reset_at string Datetime at which to reset tier system.
reset_interval string Interval of time between tier system resets.
last_reset_at string Datetime at which the tier system was last reset.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Information on a Specified Tier

Retrieves all the details related to a specific tier, including its system information.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/tiers/:tier_ID

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter Description
api_key Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
tier_ID Identifier that specifies the tier being retrieved.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains tier and tier_system objects, as shown below:

▿ JSON Response

{
  "status": "ok",
  "tier": {
    "id": 2,
    "name": "bronze",
    "identifier": "bronze",
    "next_tier_id": 3,
    "required_num_days_in_tier": 10,
    "required_points": 500,
    "required_application_achievement_ids": "1,2\n",
    "required_num_achievements": 3,
    "max_inactive_days": 10,
    "required_application_achievement_id": 1,
    "num_days_to_earn_required_achievement": 50,
    "required_sponsor_points": 10,
    "multiplier": "1.0",
    "tier_system_id": 2,
    "maintenance_required_points": 100
  },
  "tier_system": {
    "id": 2,
    "name": "1",
    "external_id": "t1",
    "active": true,
    "reset_at": "2017-05-27T04:00:00Z",
    "reset_interval": "yearly",
    "last_reset_at": "2017-05-10T20:10:33Z"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code Reason
code Code not found.
message Tier ID does not exist.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

FAQ

This section of the site provides an evolving collection of common questions and best practices.

How do I get access to a SessionM Platform account?

If you are interested in leveraging the SessionM API, please contact SessionM Sales at Enterprise-CS@sessionm.com.

Am I required to use the SessionM SDK?

You are not required to use the SessionM SDK. The functionality that powers the SDK is available through the SessionM APIs.

What is the benefit of using the SessionM SDK?

The SessionM SDK handles API lifecycle, offline mode, caching and other functionality that enhances the end-user experience. Overall, it reduces your time to market and the amount of code you need to write to leverage the SessionM platform.

Which channels does the SessionM Platform support?

The SessionM Platform APIs support any channel that is internet enabled. Currently, our developers have integrated SessionM into Mobile, Web, Kiosk as well as a variety of other channels and devices.

How does the SessionM SDK behave in situations of slow or degraded connectivity?

The SessionM SDK has an offline mode by which it queues events and spools them to the server the next time connectivity improves.

Is customer data required to exist in order for a campaign to reference that customer data in targeting or content personalization?

No, the customer data does not need to exist.

Can the SessionM Platform integrate with a Data Management Platform (DMP)?

Yes, you can establish ETLs (Extract, Transform and Load) to link SessionM with your DMP.

Is the SessionM Platform a data warehouse?

The SessionM Platform is not a data warehouse in the traditional sense, but it does have a data warehouse component to connect into your Business Intelligence (BI) and Analytics initiatives.

How do I get a set of API authentication credentials for the application or web site I'm integrating with the SessionM Platform?

API credentials are generated when you register your site or application as a property of the SessionM Platform. For more information, see Before You Begin.

What is a SessionM API key and an S2S API secret?

Server-to-server credentials that are required of every call to the SessionM Platform. For more information, see Before You Begin.

▿ Unsetting Attribute Values

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "user":{
    "gender":null
  }
}
' 'http://API.HOST.NAME/priv/v1/apps/APP_ID/external/users/EXTERNAL_ID'

How do I unset an attribute value in a JSON request?

If you need to unset a value for a particular attribute you are specifying in a JSON request, you can generally just set the value to null.