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 associated 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 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.

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 managing access tokens for customer logins (Access Tokens API), building hierarchies of related customers (Customer Affiliation API), representing a customer's devices (Devices 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 APIs that manage campaigns at a basic level (Campaigns API) as well as APIs with development objects that support a programmatic implementation of an entire campaign hierarchy (Campaigns Management API). 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 contains a few core APIs that support customer loyalty programs, including the following:

Note that the bulk of the platform's loyalty API documentation resides in the Swagger libraries for the Offers, Incentives, Catalog and Transactions domains. For more information, consult your SessionM customer success contact.

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.

Finally, the Deprecated grouping houses any API that has been deprecated in favor of newer API versions. These APIs, however, are being supported for legacy implementations.

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).

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).

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.

  6. With these credentials and an API endpoint, you can specify a URL for any SMP transaction. For example, when making REST API calls in support of standard profiles for customers, the URL appears as follows: https://{{hostname}}/priv/v1/apps/{{api_key}}/users.

After you have established your server-to-server credentials, you can generate a client-to-server token using a server-to-server API call.

Customers

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

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 a way to grant customers login access. 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Identity Services API

This API supports a login service which enables customers (endusers) of a web-based or mobile property to authenticate themselves to the SessionM Platform in order to gain access to their program. It uses the OAuth2 protocol for login and registration.

You can implement a registration workflow with the Customer Profile API or by developing your own login form. These APIs allow sign-in using a password provided to a customer in an email or using a social login. In addition, the SMP Identity service supports resetting or updating passwords.

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

Authorize a Customer for an Identity Service

Authorizes, or directs, the customer to the SMP identity service. If they don't have an active session, they are prompted to log in or create an account. After doing so, they are prompted to grant permission to the client application so it can access their user data. Then they are redirected back to the specified redirect URI, with an authorization code.

This authorization code can be exchanged for an access token, which can retrieved by the endpoint detailed in Fetch an Access Token for an Authorized Customer.

Note that this authorization endpoint can pass a request using either parameters or a JSON request object.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /<identity service URL>/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

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

Endpoint Parameter Description
response_type Required. String. Specifies that the application is requesting an authorization code grant. Default value is code. Note that token, for implicit grants, is not supported.
client_id Required. String. How the API identifies the application. Provides client ID that was specified during OAuth application setup.
redirect_uri Required. String. The URI that the identity service redirects to after successful user authentication.
scope String. The scope of the access request. This must be openid in order to retrieve an ID token.
state String. Passed to the redirect URI as a URL parameter.
prompt String. Prompts the user to re-authenticate, even if they are already logged in. Default value is login.

Request Object

When this method runs, it can take either parameters in the endpoint or a request object that contains the details shown below:

▿ JSON Request

{
    "client_id": "sample_client_id",
    "response_type": "code",
    "redirect_uri": "https://example.com/callback_url"
}


The request object's attributes are detailed in Endpoint Parameters.

The response to this request is an HTTP 302 status code to the redirect URI, with the authorization code included as a parameter in the URL. So, if the redirect_uri is https://example.com/oauth/callback, the browser redirects to https://example.com/oauth/callback?code=exampleauthcode.

Response Object

Not applicable.

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_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client The client is not authorized to request an authorization code using this method.
access_denied The resource owner or authorization server denied the request.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
invalid_scope The requested scope is invalid, unknown, or malformed.
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

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

Fetch an Access Token for an Authorized Customer

Fetches the access token for an authorized customer. This access token would be available after having been exchanged for the authorization code. If the request used to authoize the customer was set to openid, then the identity token would also be available.

This is a server-to-server request that must be done before the response is rendered on the redirected page. The access token can then be passed to the rendered application if needed for authorization for AJAX requests. The response is a JSON object containing the access token, token duration, scopes, time token was created, and, if the openid scope was specified, the ID token.

Access tokens should be cached client-side in order to access protected resources that belong to the user. Tokens last for two weeks. They can be refreshed by using the token refresh endpoint.

Note that this fetch endpoint can pass a request using either parameters or a JSON request object.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /<identity service URL>/oauth/token?grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Endpoint Parameters

Endpoint Parameter Description
grant_type Required. String. Must be authorization_code. This grant type is optimized for server-side applications, ensuring that source code is not publicly exposed and client secret confidentiality is maintained.
code Required. String. Authorization code passed to the customer agent after the authorization request.
redirect_uri Required. String. The URI that the identity service redirects to after successful user authentication. Must match redirect_uri specified in the authorization request.
client_id Required. String. How the API identifies the application. Provides client ID that was specified during OAuth application setup.
client_secret Required. String. The client_secret value specified during OAuth application setup.

Request Object

When this method runs, it can take either parameters in the endpoint or a request object that contains the details shown below:

▿ JSON Request

{
    "grant_type": "authorization_code",
    "code": "41d407a0824a5b6b8f3a5f29",
    "redirect_uri": "https://example.com/callback_url",
    "client_id": "sample_client_id",
    "client_secret": "secret"
}


The request object's attributes are detailed in Endpoint Parameters.

Response Object

In addition to a status value-pair for the transaction, the response object contains the attributes shown in the sample below:

▿ JSON Response

{
 "access_token": "070fd79c35ee0e51a0a1804e41d407a0824a5b6b8f3a5f2966654baba4ac792a",
 "token_type": "bearer",
 "expires_in": 6637,
 "refresh_token": "bb72e4d1c93e104a3814c5500dac028e900d8c2838a0676c2e4a915436ab47ff",
 "scope": "openid profile email address phone",
 "created_at": 1480622573,
 "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkZxNmlmZjMzTHh5Q3NEYS1nLXhnWG9Vc2RyTUpsLWpkTExmQ1UtUVRDVjgifQ.eyJpc3MiOiJodHRwOi8vY2JsYXRjaGxleS1tYnAuaS5zZXNzaW9ubS5jb206MzAwOCIsInN1YiI6ImQyMTIwYjQ0LWFiNjUtMTFlNi04NWI5LTA4Mjg4OWFiZjhjMyIsImF1ZCI6ImIzYTQ4N2NiMTg1ZmZlNTEyMDQ4ZTFkOWM2YWNkNTJkMTZjMzM4YzY2N2RiZTk1NDc3NDk1OTJmZDE1MjA0MGIiLCJleHAiOjE0ODA2MjMyNTYsImlhdCI6MTQ4MDYyMzEzNiwiYXV0aF90aW1lIjoxNDgwNjIzMTM2fQ.BdsWS4zlMvADPIMMsplxeJ_CXMYXcXccDGd3iFLBT_RqTo4LwEQJmteQxncHAIpKRuMeNKOKfgfK4fbTo9gIamhQ_YO0yq4FSCQ96OLtOh6Aqj4S4fF_h1P-sb-iTxrCBZkdK154xJS4fMyxG8vQLwtS-b1lNv_ai40-Gn0qcdAi1wfdiK3OXS5lCU-UtFrcDFOjJF5uIkmdN2jIyKCXvZwD0GYdBiIGwlRZNZDc6y0O1oBU2toeuQee5Zoy-sBpgcOhF7F-Zhr_y3yzPwJqAn9liXres7Gn9Xdiwfc7MZibHdXn5wf21UN4IjZxK8ASjOCqf-8oZr9EFn7PoaU9HA"
}


The following table documents this object:

Response Attributes

Attribute Type Description
access_token string String. Access token granted from the token endpoint.
token_type string Always set to bearer.
expires_in integer Number of seconds elapsed since created_at timestamp.
refresh_token string Refresh token from the original token request.
scope string The scope of the access request. This must be openid in order to retrieve an ID token.
created_at timestamp UNIX timestamp for when token was generated.
id_token string Identifier of token.

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.

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

Code Reason
invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client The client is not authorized to request an authorization code using this method.
access_denied The resource owner or authorization server denied the request.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
invalid_scope The requested scope is invalid, unknown, or malformed.
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

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

Refresh an Access Token for an Authorized Customer

Refreshes the access token for an authorized customer. The response is a JSON object containing the access token, token duration, scopes, and the time the token was created.

Access tokens should be cached client-side in order to access protected resources that belong to the user. Tokens last for two weeks. If you need more information on how to fetch them, see the fetch endpoint.

Note that this refresh endpoint can pass a request using either parameters or a JSON request object.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /<identity service URL>/oauth/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN&redirect_uri=CALLBACK_URL&client_id=CLIENT_ID


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter Description
grant_type Required. String. Must be refresh_token.
refresh_token Required. String. Refresh token from the original token request.
redirect_uri String. The URI that the identity service redirects to after successful user authentication. Must match redirect_uri specified in the authorization request.
client_id Required. String. How the API identifies the application. Provides client ID that was specified during OAuth application setup.

Request Object

When this method runs, it can take either parameters in the endpoint or a request object that contains the details shown below:

▿ JSON Request

{
    "grant_type": "refresh_token",
    "refresh_token": "71d407ab8f3a5f29",
    "redirect_uri": "https://example.com/callback_url",
    "client_id": "sample_client_id"
}


The request object's attributes are detailed in Endpoint Parameters.

Response Object

In addition to a status value-pair for the transaction, the response object contains the attributes shown in the sample below:

▿ JSON Response

{
 "access_token": "070fd79c35ee0e51a0a1804e41d407a0824a5b6b8f3a5f2966654baba4ac792a",
 "token_type": "bearer",
 "expires_in": 6637,
 "refresh_token": "bb72e4d1c93e104a3814c5500dac028e900d8c2838a0676c2e4a915436ab47ff",
 "scope": "openid profile email address phone",
 "created_at": 1480622573
}


The following table documents this object:

Response Attributes

Attribute Type Description
access_token string String. Access token granted from the token endpoint.
token_type string Always set to bearer.
expires_in integer Number of seconds elapsed since created_at timestamp.
refresh_token string Refresh token from the original token request.
scope string The scope of the access request. This must be openid in order to retrieve an ID token.
created_at timestamp UNIX timestamp for when token was generated.

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_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client The client is not authorized to request an authorization code using this method.
access_denied The resource owner or authorization server denied the request.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
invalid_scope The requested scope is invalid, unknown, or malformed.
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

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

Fetch an Access Token for an OAuth 2 Client

Fetches an access token for an OAuth 2 client application that can make API requests of the SMP Identity Service using client credentials, including a client ID and client secret.

Subsequent S2S API requests to the SMP can be authenticated using the access token by passing it as a bearer token in the HTTP authorization header.

Note that this endpoint can pass a request using either parameters or a JSON request object.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /<identity service URL>/oauth/token?grant_type=client_credentials&client_id=my_client_id&client_secret=my_client_secret


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter Description
grant_type Required. String. Must be client_credentials.
client_id Required. String. How the API identifies the client application. Provides client ID that was specified during OAuth application setup.
client_secret Required. String. Provides client secret that was specified during OAuth application setup.

Request Object

When this method runs, it can take either parameters in the endpoint or a request object that contains the details shown below:

▿ JSON Request

{
    "grant_type": "client_credentials",
    "client_id": "sample_client_id",
    "client_secret": "sample_client_secret"
}


The request object's attributes are detailed in Endpoint Parameters.

Response Object

In addition to a status value-pair for the transaction, the response object contains the attributes shown in the sample below:

▿ JSON Response

{
  "access_token": "070fd79c35ee0e51a0a1804e41d407a0824a5b6b8f3a5fa4ac792a2",
  "created_at": 1553199154,
  "expires_in": 1209599,
  "scope": "openid",
  "token_type": "bearer"
}


The following table documents this object:

Response Attributes

Attribute Type Description
access_token string String. Access token granted from the token endpoint.
created_at timestamp UNIX timestamp for when token was generated.
expires_in integer Number of seconds elapsed since created_at timestamp.
scope string The scope of the access request. This must be openid in order to retrieve an ID token.
token_type string Always set to bearer.

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_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client The client is not authorized to request an authorization code using this method.
access_denied The resource owner or authorization server denied the request.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
invalid_scope The requested scope is invalid, unknown, or malformed.
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

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

Fetch User Information for a Customer

Fetches user information pertaining to a customer according to the scope granted by the authorization request. Common scopes used alongside openid are profile, gender, email, and phone. The response is a JSON object containing the access token and any applicable scopes.

Access tokens should be cached client-side in order to access protected resources that belong to the user. Tokens last for two weeks. If you need more information on how to fetch them, see the fetch endpoint.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET/POST /<identity service URL>/oauth/userinfo?access_token=ACCESS_TOKEN


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter Description
access_token Required. String. Access token granted from the token endpoint.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object contains the attributes shown in the sample below:

▿ JSON Response

{
  "sub": "d2120b44-ab65-11e6-85b9-082889abf8c3",
  "email": "example_user@example.com",
  "name": "Example User",
  "gender": "m",
  "family_name": "bkl_Last",
  "given_name": "bkl_First",
  "dob": "1970-10-10",
  "zip_code": "85360",
  "country": "USA"
}


The following table documents this object:

Response Attributes

Attribute Type Description
sub string Value from user_id.
email string Email associated with customer.
name string Name associated with customer.
gender string Gender of customer.
family_name string Family last name associated with customer.
given_name string First name associated with customer.
dob string Date of birth of customer.
zip_code string Zip code associated with customer.
country string Country associated with 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. 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.

Log a Customer in with a User Name and Password

Logs a customer in with a user name and password, which would be collected by the client and sent to the identity server in exchange for an access token. This flow should only be used by trusted applications, as this makes phishing very easy. This requires a single API call to the token endpoint.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /<identity service URL>/oauth/token


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter Description
identity service URL Required. String. URL for identity service.

Request Object

When this method runs, it can take either parameters in the endpoint or a request object that contains the details shown below:

▿ JSON Request

{

  "grant_type": "password",
  "email": "customer@acme.com",
  "password": "customer password",
  "client_id": "sample_client_id"
}


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

Request Attributes for Token

Attribute Type
Required/Optional
Description
grant_type String
Required
Must be password.
email String
Required
Customer's email.
password String
Required
Customer's password.
client_id String
Required
How the API identifies the application. Provides client ID that was specified during OAuth application setup.
scope String
Optional
Scopes requested. User consent is inferred by providing username and password.

Response Object

In addition to a status value-pair for the transaction, the response object contains the attributes shown in the sample below:

▿ JSON Response

{
  "access_token": "3403dda4e237da6fb18358a806e111b78c27765fc20465e78afe268b3bac6731",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "bd3fd47fdddb79f026e9f939215be49364c269834d16394c4a70c4546a82e22c",
  "scope": "openid profile email address phone",
  "created_at": 1480951282
}


The following table documents this object:

Response Attributes

Attribute Type Description
access_token string String. Access token granted from the token endpoint.
token_type string Always set to bearer.
expires_in integer Number of seconds elapsed since created_at timestamp.
refresh_token string Refresh token from the original token request.
scope string The scope of the access request. This must be openid in order to retrieve an ID token.
created_at timestamp UNIX timestamp for when token was generated.

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_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client The client is not authorized to request an authorization code using this method.
access_denied The resource owner or authorization server denied the request.
unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
invalid_scope The requested scope is invalid, unknown, or malformed.
server_error The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

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

Request an ID Token for a Password Reset Email a Customer can Use to Reset their Password

Makes a request for an ID token to incorporate into a password reset link that can be emailed to a customer. Once received, the customer can use the reset link to update, or change, their password. Note that this endpoint must be called twice, each time with a different request object: once with the request object for the ID token, and then again with the request object for actually changing the password.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/users/:user_id/perform


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Request Objects

When this method runs, it can take either a sendPasswordResetEmail or a updatePassword object.

Request for Sending Password Reset Email

▿ JSON Request

{
    "sendPasswordResetEmail":{
        "email": "test@example.com",
        "send_email": false
    }
}


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

Request Attributes for Sending Password Reset Email

Attribute Type
Required/Optional
Description
email string
required
Customer's email address.
send_email boolean
required
States whether or not email is to be sent: true to send email; false to not send email and only return tokens and links. Setting to false can be used for a manual send.
Request for Changing Password

▿ JSON Request

{

    "updatePassword": {
        "token": "RmdTUWhUU0dSMkJVQTRqUGF1MG9tSS8zY0pya2thNE9kS0hvbTM4OFl2cz0tLXRzYUhoZHE4TFIxcjhEMlNKbjlhRjd1b0diOWswbXZFTmY0bER2cnFseW9PcW1lZFJlM2Y1MWdlWHRsV0x1YWRSaXN5V3VGanhVQjVXQmVQN0dxSk8wcWY2YXhZQ1pJbzVSOFJ4Z2hFa0xtUzFCWE9sNWl4NW5XL1RiVWp4NzF3ZHUwdE5BPT0=",
        "password": "Password1"
    }
}


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

Request Attributes for Updating Password

Attribute Type
Required/Optional
Description
token string
required
ID token associated with customer updating password.
password string
required
New password.

Response Objects

In addition to a status value-pair for the transaction, the response contains a user object. The attributes vary depending on whether you're sending a password reset email or updating a password.

Response for Sending Password Reset Email

▿ JSON Response

{
    "status": "ok",
    "user": {
        "send_email": false,
        "verification_string": "RmdTUWhUU0dSMkJVQTRqUGF1MG9tSS8zY0pya2thNE9kS0hvbTM4OFl2cz0tLXRzYUhoZHE4TFIxcjhEMlNKbjlhRjd1b0diOWswbXZFTmY0bER2cnFseW9PcW1lZFJlM2Y1MWdlWHRsV0x1YWRSaXN5V3VGanhVQjVXQmVQN0dxSk8wcWY2YXhZQ1pJbzVSOFJ4Z2hFa0xtUzFCWE9sNWl4NW5XL1RiVWp4NzF3ZHUwdE5BPT0=",
        "reset_link": "https://login-economy.stg-sessionm.com/c6b7e6f1ea04f6ad3e57cb84059865dfb0555b33/accounts/reset_password?token=RmdTUWhUU0dSMkJVQTRqUGF1MG9tSS8zY0pya2thNE9kS0hvbTM4OFl2cz0tLXRzYUhoZHE4TFIxcjhEMlNKbjlhRjd1b0diOWswbXZFTmY0bER2cnFseW9PcW1lZFJlM2Y1MWdlWHRsV0x1YWRSaXN5V3VGanhVQjVXQmVQN0dxSk8wcWY2YXhZQ1pJbzVSOFJ4Z2hFa0xtUzFCWE9sNWl4NW5XL1RiVWp4NzF3ZHUwdE5BPT0="
    }
}


The following table documents this object:

Response Attributes for Sending Password Reset Email

Attribute Type Description
send_email boolean States whether or not email is to be sent: true to send email; false to not send email and only return tokens and links. If set to false, can be used for a manual send.
verification_string string Verification string to be sent to the resetPassword endpoint - if done manually.
reset_link string Link to web page where a user can reset their password.
Response for Updating Password

▿ JSON Response

{
    "status": "ok",
    "user": {}
}

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 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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",
     "address2":"8 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.
address2 string
optional
Customer's secondary 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. Cannot contain special characters.
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",
    "address2":"8 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.
address2 string Customer's secondary 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. Cannot contain special characters.
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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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/?user_ids[]=:user_id1&user_ids[]=:user_id2&show_identifiers=true


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 based on attributes such as email address, external ID, and mobile phone number. 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_users?email=test@example.com
GET /priv/v1/apps/:api_key/users/search_users?external_id=eutest17&user
GET /priv/v1/apps/:api_key/users/search_users?mobile_number=5089959991


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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. For example: user[user_profile]=true
expand_incentives Optional boolean that returns loyalty related detail data. For example: expand_incentives=true
show_identifiers Optional boolean that displays a list of external identifiers and their corresponding types for customers. For example: 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Please note: Once you've created a new attribute in a custom profile model, it cannot be changed or deleted. This limitation, however, does not preclude modifying the existing value for a custom attribute. For more information on that, see Update a Combined Standard and Custom Profile, Update a Custom Profile, or Patch an Attribute in a Custom Profile.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Retrieve Product Recommendations Associated with a Custom Profile

Retrieves the product recommendations associated with a specified custom profile.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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[__platform_recommendations]=true Indicates that all product recommendations defined for the organization model be retrieved for a specified customer. Must be set to true.
Request Object

Not applicable

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method includes a user object, which contains the __platform_recommendations object shown below:

▿ JSON Response

{
    "status": "ok",
    "user": {
        "id": "1a5b425f-e112-11e8-b6e3-0242ac110010",
        "external_id": "0000584B98531BDB980D66836D7DBE9D2A85D8547FEF3B9DD51913E84055184B",
        "opted_in": true,
        "activated": false,
        "proxy_ids": [],
        "email": "test785698@example.com",
        "created_at": "2018-11-05 15:47:30",
        "updated_at": "2018-11-05 15:47:30",
        "country": "USA",
        "locale": "en-us",
        "suspended": false,
        "last_name": "Smith",
        "first_name": "Jim",
        "registered_at": "2018-11-05 15:47:30",
        "profile_photo_url": "/images/account-neutral.png",
        "account_status": "good",
        "current_country": "USA",
        "referrer_code": "JIMS-919847",
        "__platform_recommendations": {
            "_version": 4,
            "products": {
                "set_01": {
                    "rank_5": {
                        "id": "5717abd-2c01-49fc-b15f-ce7911b7fc7f",
                        "name": "ACME Special",
                        "score": 0.5,
                        "confidence": 0.5
                    },
                    "rank_1": {
                        "id": "9bf21463-35ef-4acf-aa55-4db39027c9b7",
                        "name": "ACME Regular",
                        "score": 0.5,
                        "confidence": 0.5
                    },
                    "top_k": [
                        "9bf21463-35ef-4acf-aa55-4db3902c9b7",
                        "19bae76-712d-44ba-bf13-83038fba85d9",
                        "f1bfd29c-9fcb-408f-8a2e-9d579fc1101",
                        "0c2e41b-b345-42d9-a4eb-fc1c4572a600",
                        "5717abd-2c01-49fc-b15f-ce7911b7fc7f",
                        "f4c9d0b-fdd4-4972-ae2d-181eb8f18732",
                        "310ec5d-37b0-4cd9-b7fc-496178ba0f7a",
                        "ad838fd-14ee-43cd-8c87-ed11c5d30967",
                        "7bf3c3f-0ed0-47d4-bda4-37943c270b64",
                        "d98b85a-c575-4c6e-a1b8-28b9a9d76e0d"
                    ],
                    "rank_7": {
                        "name": "ACME Deluxe",
                        "score": 0.5,
                        "confidence": 0.5,
                        "id": "310ec5d-37b0-4cd9-b7fc-496178ba0f7a"
                    },
                    "rank_9": {
                        "confidence": 0.5,
                        "id": "7bf3c3f-0ed0-47d4-bda4-37943c270b64",
                        "name": "ACME Master",
                        "score": 0.5
                    },
                    "tag": "all_items",
                    "rank_6": {
                        "score": 0.5,
                        "confidence": 0.5,
                        "id": "f4c9d0b-fdd4-4972-ae2d-181eb8f18732",
                        "name": "ACME Junior"
                    },
                    "rank_4": {
                        "name": "ACME Student",
                        "score": 0.5,
                        "confidence": 0.5,
                        "id": "0c2e41b-b345-42d9-a4eb-fc1c4572a600"
                    },
                    "id": "01f1d76e-f573-11e8-bce0-c3dfebd4bf4b",
                    "rank_3": {
                        "score": 0.5,
                        "confidence": 0.5,
                        "id": "f1bfd29c-9fcb-408f-8a2e-9d579fce1101",
                        "name": "ACME Teen"
                    },
                    "rank_8": {
                        "id": "ad838fd-14ee-43cd-8c87-ed11c5d30967",
                        "name": "ACME Holiday",
                        "score": 0.5,
                        "confidence": 0.5
                    },
                    "description": "test_1",
                    "rank_2": {
                        "score": 0.5,
                        "confidence": 0.5,
                        "id": "19bae76-712d-44ba-bf13-83038fba85d9",
                        "name": "ACME Sunday"
                    },
                    "rank_10": {
                        "confidence": 0.5,
                        "id": "d98b85a-c575-4c6e-a1b8-28b9a9d76e0d",
                        "name": "ACME Carribean",
                        "score": 0.5
                    }
                },
                "version": "1.0"
            }
        },
        "phone_numbers": [
            {
                "phone_number": "5555555555",
                "preference_flags": [],
                "verified_ownership": false
            }
        ]
    }
}


The following tables document this object:

Response Attributes for Platform Recommendations Object

Attribute Type Description
_version number Attribute reserved for SessionM use only.
products object Contains sets of product and/or product category recommendations. Each products object is comprised of one or more child set objects, within which are rank objects. Note too that this object contains a version attribute. For information on the products object's attributes, see the table detailing the products object.

Response Attributes for Products Object

Attribute Type Description
set object Each set object denotes a grouping of any combination of sub-brands, regions, catalog categories. Within it, are one or more rank objects, each of which details a product recommendation. For information on the set object's attributes, see the table detailing the set object. Note too that sets contain top objects, which are reserved for SessionM use only. For set configuration options, consult with a SessionM integration engineer.
version string Version of schema.

Response Attributes for Set Object

Attribute Type Description
rank object Each rank object contains a few product recommendation attributes and reflects whatever numeric ranking has been assigned to it by the system. For information on the rank object's attributes, see the table detailing the rank object.
top_k array An listing of top "K" item IDs. Value of "K", which defaults to 10, is configurable; but the field name "top_k" does not change.
tag string Tag reference for the set.
id string Reserved for SessionM use only.
description string Free form textual description of the set.

Response Attributes for a Rank Object

Attribute Type Description
id string Identifier for recommended product.
name string Name of recommended product.
score number Number between 0 and 1 which denotes the customer's affinity for this product.
confidence number Number between 0 and 1 which denotes the confidence in the score above.
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 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Clear a Custom Profile Attribute

Using this method, you can clear a custom profile attribute of an existing value. By setting a user_profile attribute to "null", you ensure the attribute is neither returned in GET calls nor shown in the SMP. If you want to remove all attributes - something you might consider to comply with a GDPR policy - you must list each one and set it to "null" via a PUT. Note that the customer and their standard profile remain intact.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 object, as shown below:

▿ JSON Request

{  
   "user":{  
      "user_profile": {  
         "custom_attr_1": null,
         "custom_attr_2": null,
         "custom_attr_3": null
      }
   }
}


The user object contains a user_profile object with several custom attributes. Each of these attributes are set to "null". This clears the value from the customer profile attribute.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a user object that holds any objects or attributes that were not nulled out, along with a user_profile object emptied of whatever attributes had been set to "null". The user_profile object shown below has been emptied of all customer attributes; by default, only the _version attribute remains:

▿ JSON Response

{  
   "status": "ok",
   "user": {  
      "user_profile": {  
         "_version": 84
      }
   }
}
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 Attribute set to "null" doesn't exist, or is "unknown".

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.

Note that all operations in this API specify content type differently than the vast majority of APIs in the platform. Most platform APIs specify content type as Content-Type: application/json. However, when patching an attribute in a custom profile, content type must be specified as follows: Content-Type: application/json-patch+json.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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:

Bear in mind that all operations associated with patching an attribute in a custom profile require that their content type be specified as follows: Content-Type: application/json-patch+json.

▿ 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 Accounts Merge API

This API allows you to merge customer accounts as well as retrieve merge entry information after the merge. Often necessary when external users being added to the SessionM Platform have existing profile data that must be merged with the newly created, internal profile on the platform. Merging profiles presumes two types of customer profiles exist: the survivor, or primary, profile and the victim, or merged, profile. When the merge completes successfully, the victim profile is considered deleted. The profile is not returned by any queries, although it does technically still exist in the database.

Strategies for what profile content is actually merged can be determined by each organization. By default, point balances, tier points (not incentive tiers), transfer transactions, external IDs, and re-process events are all merged data. However, there are other options, including event stream events for transfers.

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

Merge Customer Accounts

Merges one customer account into another customer account. Bear in mind that the ability to undo a merge is currently NOT supported.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/external/users/:survivor_external_id/merge_accounts


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
survivor_external_id External ID for the survivor, or primary, customer profile.

Request Object

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

▿ JSON Request

{
  "merge_account":
    {
      "external_id": "victim_external_id"
    }
}


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

Request Attributes for Merge Account

Attribute Type
Required/Optional
Description
external_id string or integer
required
External ID for the victim, or merged, customer profile.

Response Object

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

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "merge_account": {
        "id": 2,
        "primary_user_id": "30c556d6-c735-11e8-9e3a-831a00372c90",
        "merged_user_id": "2070e812-c349-11e8-82f7-23d300372c90",
        "merged_at": "2018-10-03T18:06:25Z",
        "available_points": 31,
        "behaviors": {},
        "deltas": {},
        "status": "completed"
    }
}


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

Response Attributes for Merged Account

Attribute Type Description
id string Identifier of the MergeAccount record within our database.
primary_user_id string Internal GUID for survivor profile.
merged_user_id sting Internal GUID for the victim profile.
merged_at string Timestamp for the merge event.
available_points integer New balance for the survivor account after doing the merge
behaviors object Same as the Events API response field.
deltas object Same as the Events API API response field.
status string Status of the merge. Possible values include "completed" and "in_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
validation Can't merge same user. Occurs when victim and survivor accounts are the same.
missing_data Missing merge data. Occurs when request body is missing merge_account data, typically when content-type is incorrect.
access_denied Merge accounts not enabled.

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

Retrieve Merge Information

Fetches the merge entry, with its information, for the customer accounts merge.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/external/users/:survivor_external_id/merge_accounts/:merge_account_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
survivor_external_id External ID for the survivor, or primary, customer profile.
merge_account_id ID of the merge_account entry, which is included in the response for the POST operation discussed in Merge customer accounts.

Request Object

Not applicable.

Response Object

Since this method's response object is identical to what is returned for the method that performs the customer accounts merge, see the "Response Object" section in Merge customer accounts 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. 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 Account Notes API

This API allows you to create and maintain comments on a particular customer. Once created, the comments are visible within the customer's record, which is accessible in the Notes tab of the Customers Module.

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

Add Notes to a Customer Account

Adds comments to a customer account.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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_account_comment object, as shown below:

▿ JSON Request

{
    "user_account_comment": {
        "comment": "testComment",
        "admin_id": 1
    }
}


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

Request Attributes for User Account Comment

Attribute Type
Required/Optional
Description
comment string
required
Free form comments being added to notes maintained for customer.
admin_id integer
required
Account identifier of the SMP account, which is different from the user account.

Response Object

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

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user_account_comment": {
        "id": 3,
        "player_user_id": "c0b1fd0a-cd55-11e8-8fa6-845889cb62b1",
        "comment": "testComment",
        "commented_by": "AdOps Admin",
        "updated": false,
        "created_at": "October 12, 2018 14:48",
        "updated_at": "October 12, 2018 14:48",
        "reason_text": "No Reason Given"
    }
}


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

Response Attributes for User Account Comment

Attribute Type Description
id integer Identifier for comment.
player_user_id string Identifier for user that comment applies to.
comment string Comment displayed in notes field.
commented_by string SMP account name; comes from admin_id.
updated boolean Specifies whether record was updated, true or false.
created_at string Date that comment was created.
updated_at string Date of last update to comment.
reason_text string Reason selected when comment 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.

Retrieve a Note on a Customer Account

Retrieves a specific note on a customer account.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/external/users/:external_id/user_account_comments/ID
GET /priv/v1/apps/:api_key/external/users/:user_id/user_account_comments/ID


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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_account_comment object.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user_account_comment": {
        "id": 3,
        "player_user_id": "c0b1fd0a-cd55-11e8-8fa6-845889cb62b1",
        "comment": "testComment",
        "commented_by": "AdOps Admin",
        "updated": false,
        "created_at": "October 12, 2018 14:48",
        "updated_at": "October 12, 2018 14:48",
        "reason_text": "No Reason Given"
    }
}


For attribute information on a user_account_comment response object, see the Response Attributes for User Account Comment 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.

Retrieve All Notes on a Customer Account

Retrieves all notes on a customer account.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/external/users/:external_id/user_account_comments
GET /priv/v1/apps/:api_key/external/users/:user_id/user_account_comments


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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_account_comments array. In this array are multiple user_account_comment objects.

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user_account_comments": [
        {
            "id": 3,
            "player_user_id": "c0b1fd0a-cd55-11e8-8fa6-845889cb62b1",
            "comment": "testComment",
            "commented_by": "AdOps Admin",
            "updated": false,
            "created_at": "October 12, 2018 14:48",
            "updated_at": "October 12, 2018 14:48",
            "reason_text": "No Reason Given"
        },
        {
            "id": 5,
            "player_user_id": "c0b1fd0a-cd55-11e8-8fa6-845889cb62b1",
            "comment": "testComment2",
            "commented_by": "AdOps Admin",
            "updated": false,
            "created_at": "October 12, 2018 15:47",
            "updated_at": "October 12, 2018 15:47",
            "reason_text": "No Reason Given"
        }
    ]
}


For attribute information on a user_account_comment response object, see the Response Attributes for User Account Comment 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.

Update a note on a Customer Account

Updates a comment on a customer account.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/external/users/:external_id/user_account_comments/ID
PUT /priv/v1/apps/:api_key/users/:user_id/user_account_comments/ID


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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_account_comment object, as shown below:

▿ JSON Request

{
    "user_account_comment": {
        "comment": "updatedTestComment",
        "admin_id": 1
    }
}


For attribute information on a user_account_comment request object, see the Request Attributes for User Account Comment table.

Response Object

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

Consider the following sample:

▿ JSON Response

{
    "status": "ok",
    "user_account_comment": {
        "id": 3,
        "player_user_id": "c0b1fd0a-cd55-11e8-8fa6-845889cb62b1",
        "comment": "UPDATEtestComment2",
        "commented_by": "AdOps Admin",
        "updated": true,
        "created_at": "October 12, 2018 14:48",
        "updated_at": "October 12, 2018 14:48",
        "reason_text": "No Reason Given"
    }
}


For attribute information on a user_account_comment response object, see the Response Attributes for User Account Comment 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.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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
required
Unique customer ID of the parent 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.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 a required 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
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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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/:parent_id/children


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
parent_id Internal identifier for the parent node of the child nodes being retrieved.
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.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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. 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.

Note that if no devices are assigned to the user, the API returns an empty array of devices.

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. Note that purchase events are supported for legacy implementations only. For any new development, please use the Transactions API.

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" : { "opened_app": 1 }
}

Complex Event Submissions

The complex event submission allows the caller of the API to submit additional metadata related to the event. For example, the following sample request is an event for a customer that downloaded an application:

▿ Complex Event Submission

{
  "events": {
    "app_downloaded": {
      "context" : {
        "app_name": "New Cool App",
        "version": "1.0",
        "downloaded_at": "2019-12-17T17:49:51Z"
      }
    }
  }
}


Within the contents of the request, there is a context payload object. Using it, you can create a request that works in tandem with campaigns where the eligibility is determined by the key/value pair within the context payload object.

For example, an event with the context.version value of 1.0 can have different outcomes than an event where the value is 2.0. This allows the client to design their own event schema (not maintained in the SessionM Platform) that can be easily updated at any time. Currently, the context payload object does not support nested object types. This requires the client to have a flat schema in order to properly use the feature. The current supported types for the values with the context payload object are:

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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)

{
    "date": "2016-02-02T17:00:00Z",
    "events": {
        "opened_app": 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 can convey a variety of things about the purchase, including 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. Please note that purchase events are supported for legacy implementations only. For any new development, please use the Transactions API.

▿ 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 contains two new complementary routes that work together to allow clients to verify phone ownership, which is necessary for opting in to receive messages about their loyalty programs through SessionM.

This API has the following methods:

Create an SMS Validation Request

Creates an SMS validation request for either a mobile device or a Web form. The client application sends a request to the endpoint shown below. Doing so, logs the customer's phone into our system and sends a message to the customer's phone with a code that is used in the confirmation endpoint detailed in Create an SMS Validation Confirmation.

Important to note that this API cannot send a validation request unless a global SMS campaign exists and the opt-in keyword for that global campaign is "YES".

Endpoints

▿ REST Endpoints

POST /priv/v1/apps/:api_key/messaging_events/sms/validation/request


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Request Object

This method supplies the SMS request validation object shown below:

▿ JSON Request

{
  "external_id": "twiliofeb211",
  "to_phone_number": "13139711649",
  “message_text”: “Some message text prefixing validation code in sms: ”
}


Request Attributes for SMS Validation Request

Attribute Type
Required/Optional
Description
external_id string
required
External ID for customer.
to_phone_number string
required
Phone number being used to validate customer.
message_text string
optional
Whatever text you deem appropriate. “Validation Code: “ is default.

Response Object

This method returns the response object 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 and a string that indicates ok. However, when the string returned is error, returned errors can be either method-specific or generic.

This method can return a few different 400-level errors in the following format:

{
  "status": "Bad Request",
  "message": "Message text for error"
}

Possible message text is detailed in this table:

Code Reason
"required parameter to_phone_number missing" Customer's phone number is missing.
"required parameter validation_code missing" Customer's validation code is missing.
"Invalid validation code" Validation code provided is not valid.

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

Create an SMS Validation Confirmation

Creates a confirmation for an SMS validation request pertaining to either a mobile device or a Web form. Once the validation request is sent to get the customer's phone number logged into the SessionM system, a message with a code is sent to the customer's phone. That code is used in the endpoint detailed below to confirm the customer's phone.

Endpoints

▿ REST Endpoints

POST /priv/v1/apps/:api_key/messaging_events/sms/validation/confirm


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Request Object

This method supplies the SMS request validation object shown below:

▿ JSON Request

{
"external_id": "twiliofeb211",
"to_phone_number": "13139711649",
"validation_code": "383ue73733eee"
}


Request Attributes for SMS Validation Confirmation

Attribute Type
Required/Optional
Description
external_id string
required
External ID for customer.
to_phone_number string
required
Phone number being used to validate customer.
validation_code string
required
Validation code received on the mobile device.

Response Object

This method returns the response object 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 and a string that indicates ok. However, when the string returned is error, returned errors can be either method-specific or generic.

This method can return a few different 400-level errors in the following format:

{
  "status": "Bad Request",
  "message": "Message text for error"
}

Possible message text is detailed in this table:

Code Reason
"required parameter to_phone_number missing" Customer's phone number is missing.
"required parameter validation_code missing" Customer's validation code is missing.
"Invalid validation code" Validation code provided is not valid.

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

Data Privacy API

The SessionM Platform provides functions that support the following data privacy requests directly within the platform:

The Data Privacy API supports the creation and maintenance of 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 marketing programs as well as to app or web portal access - if using SessionM’s identity services product. These data privacy features are available to all clients committed to fulfilling customer requests seeking to safeguard or review their own personal data.

Note that not all of the Data Privacy functionality is available via platform APIs. In some cases, such as data exports, the API supports the submission of export requests, but not the retrieval of the exported data file. For that, the SessionM Platform operator must retrieve the customer’s data files via the customer profile UI for that specific customer. For more information, see the article that details the implementation of Data Privacy in the SessionM Platform UI and any dependencies between the UI and the APIs.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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",
            "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.
export_data_status string Status of job being run to export data for a customer. Possible values include: completed 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 Customer 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.

Before executing the request, it is recommended that a check is performed to confirm the customer’s identity and that they do, in fact, want to proceed with the erasure request. This action cannot be undone.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 Customer Data

Creates an export data request which generates a CSV file of the customer’s data. The exported CSV file contains data from a customer profile as well as any data derived from calculated metrics, purchases, marketing and loyalty program-related events, and application sessions.

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. Specifically, the following data is provided to the client:

Bear in mind that this API currently allows for the submission of requests, but the SessionM Platform operator can only get the customer’s data files from the customer profile UI for that specific customer. For more information, see this article's discussion on turnaround expectations for the export file delivery.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 Customer 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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",
        "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.
export_data_status string Status of job being run to export data for a customer. Possible values include: completed 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 participate in marketing campaigns and audience inclusion, as managed by SessionM’s Campaigns and Audiences Modules. Doing so also removes their ability to log into an app or web portal experience, if SessionM’s identity services product is used.

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 take the actions mentioned above that had restricted processing. 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 and show the tags that are already attached. 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

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.

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.

The following terms are critical to understanding campaigns and the objects they comprise:

The entities described above constitute a campaign hierarchy. Together, they represent the core types of data the platform offers for the creation and maintenance of campaigns, including the ETL activities required at the beginning of an implementation.

The Campaigns API provides a collection of APIs that correspond to the following areas of focus:

Creating Campaigns

Creates a campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/management/campaigns


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 campaign object, as shown below:

▿ JSON Request

{
  "campaign": {
    "name":"Campaign Example",
    "status":"live",
    "starts_at":"2021-12-31T05:00:00Z",
    "ends_at":"2022-01-04T05:00:00Z,
    "campaign_type": "promotion",
    "template": "promotion"
  }
}


This object is detailed in the following table:

Request Attributes for Campaign

Attribute Type
Required/Optional
Description
name string
required
Name of campaign. Must be unique.
status string
required
Defines whether the campaign is "live," "paused," "draft," "inreview," or "completed." Should be “live” for this endpoint. Users can engage with only a live campaign via actions such as triggering behaviors and receiving outcomes.
starts_at datetime
required
Timestamp when campaign becomes active.
ends_at datetime
required
Timestamp when campaign becomes inactive.
external_id string
optional
Client's own ID for campaign. If external_id parameter is not provided in request, platform generates GUID for campaign and returns it in response. This attribute serves as an alias in this API for permalink, which is the actual database field that contains the value for external_id. See more on permalink in the response object discussion below.
campaign_type string
optional
Allowed values are "promotion" and "messaging".
template string
optional
Same value as campaign_type.

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

{
  "campaign": {
    "ends_at": "2020-08-19T15:02:54Z",
    "external_id": "d4f5fc94-dcad-11ea-845e-7001986d963d",
    "id": 721,
    "metadata": {},
    "name": "Campaign Example",
    "starts_at": "2020-08-12T15:02:54Z",
    "status": "live",
    "total_budget": 0,
    "weight": 5,
    "campaign_type": "promotion",
    "template": "promotion"
  },
  "status": "ok"
}


This object is detailed in the following table.

Response Attributes for Campaign

Attribute Type Description
name string Name of campaign.
status string Defines whether campaign is "live," "paused," "draft," "inreview," or "completed." Should be “live” for this endpoint. Users can engage with only live campaign via actions such as triggering behaviors and receiving outcomes.
starts_at datetime Timestamp when campaign becomes active.
ends_at datetime Timestamp when campaign becomes inactive.
external_id string Client's own ID for campaign. If external_id parameter is not provided in request, platform generates GUID for campaign and returns it in response. This attribute serves as an alias in this API for permalink, which is the actual database field that contains the value for external_id. See more on permalink in the response object discussion below.
campaign_type string Allowed values are "promotion" and "messaging".
template string Same value as campaign_type.
id integer Database identifier.
metadata object JSON object containing any data that the user might want to attach to the campaign.
total_budget integer Legacy field.
weight integer Legacy field.

The table below documents a set of additional optional attributes that can be part of a request and appear in the response.

Additional Response Attributes for Campaign

Attribute Type Description
campaign_id integer Campaign identifier internal to SessionM.
campaign_permalink string Permanent, static hyperlink for campaign.
start_date string Campaign starting date.
end_date string Campaign end date.
permalink string GUID that can be passed to the API instead of the campaign_id (integer ID) for a campaign. Returned as an external_id in the response. This attribute is the actual database field that contains the value for external_id.
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.
opt_in_starts_at datetime Opt-in starting date.
opt_in_ends_at datetime Opt-in ending date.
reporting_ends_at datetime Timestamp when reporting data will no longer be generated for a campaign.
targeting object Serialized JSON query that is used to create ad targets.
qualify_tag string Tag used in targeting to indicate that the user is qualified. Must be included in targeting setup to function.
disqualify_tag string Tag used in targeting to indicate the user is disqualified. Must be included in targeting setup to function.
qualified boolean Current customer qualification for campaign - after domain call. For example, false can result from targeting that tags the customer and targeted away from the campaign.
group_id integer Internal ad group identifier.
creative_id integer Platform-generated ID of the ad unit content, which is also called creative content.
version string Campaign version.

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
argument_error Unknown campaign attributes test.
missing_data Missing campaign data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Opting Customers into Campaigns

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.

Note that to enable "opt-ins," a campaign must be created with optin_required set to "true": optin_required=true.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.

Retrieving Campaigns for Customers

This family of APIs allows you to:

Get All Campaigns for a Specified Customer

Fetches 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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
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,
                            "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                            "event_name": "3dac9302-68d4-11e7-9412-9e32bae62f9c",
                            "name": "TEstt0714441 Campaign Action 1",
                            "progress": 0,
                            "goal": 1
                        }
                    ]
                },
                "behaviors": {
                    "t_estt0714441 campaign action 1": {
                        "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
                        "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 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 URL if creative click tracking is disabled. Otherwise the action tracking URL is used.
tracking_urls array 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.
external_behavior_id string External 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
external_behavior_id string External ID for the behavior.
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.

Get Customer Progress for a Campaign

Fetches 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.

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=


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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,
              "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",
              "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,
                "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",                
                "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,
                "external_behavior_id": "86d77299-ed18-49ba-8fef-f8cb2241faac",                
                "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.

Get All Active Campaigns Eligible for a Customer

Fetches all active campaigns that a customer is eligible for by either internal or external user ID.

Note that these are V2 endpoints. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/campaigns
GET /priv/v2/apps/:api_key/external/users/:external_id/campaigns


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
sections[] Controls which sections of the campaign will appear. Possible values: progress includes user progress through campaign; behaviors includes all behaviors (achievements) in campaign; offers includes detailed deals request; and, redemptions includes customer redemptions.
filters[] Controls which campaigns appear for associated customer. Possible values: ineligible includes only campaigns customer is ineligible for; eligible includes just campaigns customer is eligible for; and, all includes all active campaigns, ineligible and eligible.
creatives[] Controls which creatives are shown. Leaving parameter blank removes the creative section. Possible values: promotion includes promotion section if available; and tile includes tile section if available.
Request Object

Not applicable.

Response Object

The response object returned by the method contains a status key-value pair, a few relevant attributes and a campaigns array, as shown in two sample below:

▿ JSON Response

{
  "page": 1,
  "page_size": 20,
  "number_of_pages": 1,
  "status": "ok",
  "campaigns": [
    {
      "campaign_id": 1,
      "campaign_permalink": "45650900-d457-11e7-9d65-94bc328254fd",
      "creative": {
        "tile": {
          "message": {
            "header": "Test Header",
            "subheader": "Test Subheader",
            "description": "Test Description",
            "icon_url": "http://bit.ly/foo.png",
            "image_url": "http://getm.pt/foo.png",
            "points": 20
          },
          "action": {
            "type": "open_ad",
            "url": "http://ads.host/api/v1/apps/xyz15cbf87b9068363df55fc6344e05b550e49c98060/creatives/2/stats/457869f0-d457-11e7-99dd-ee69328254fd/click/redir?auth_token=&xsid=457583c0-d457-11e7-88dd-f3698c9fdcfd&locale=en-us",
            "tracking_urls": [
              "http://ads.host/priv/v1/apps/xyz15cbf87b9068363df55fc6344e05b550e49c98060/users/457583c0-d457-11e7-88dd-f369328254fd/creatives/2/stats/457869f0-d457-11e7-99dd-ee69328254fd/seen/track?xsid=457583c0-d457-11e7-88dd-f3698c9fdcfd&locale=en-us"
            ],
            "event_meta_data": {
              "ad_unit_id": 2,
              "ad_stat_id": "457869f0-d457-11e7-99dd-ee69328254fd"
            }
          }
        }
      },
      "ends_at": "2017-12-01 16:14:55",
      "name": "Campaign 1",
      "opt_in_ends_at": "2017-12-01 16:14:55",
      "opt_in_starts_at": "2017-11-27 16:14:55",
      "qualified": false,
      "starts_at": "2017-11-27 16:14:55",
      "status": "not_qualified"
    }
  ]
}


This object is detailed in the following table:

Response Attributes for Campaigns Array

Attribute Type Description
page, page_size, number_of_pages integers Standard pagination feature informs API how many campaigns to return in a the response and where to start. If page and page_size were not provided in the request, a page_size of "20" and page of "1" is returned. This means the response contains the first 20 campaigns. The number_of_pages attribute is always the same and depends on the total number of campaigns in the database.
campaigns array Array that contains a campaign. Most of the attributes of the Campaign object are described in the Response Attributes for Campaign table. But the creative object - which resides within the campaign object - does contain a tile object described in the table below.

Response Attributes for Tile

Attribute Type Description
message object See the Response Attributes for Message table below.
action object See the Response Attributes for Action table below.

Response Attributes for Message

Attribute Type Description
header string Heading required to render tile ad.
subheader string Sub-heading to render tile ad.
description string Description in tile ad.
icon_url string URL for icon in tile ad.
image_url string URL for image in tile ad.
points string Points awarded to customer clicking on ad.

Response Attributes for Action

Attribute Type Description
type string Type of action. Options include: "open_ad", "deep_link", "external_link", "campaign".
url string URL if creative click tracking is disabled. Otherwise the action tracking URL is used.
tracking_urls array Array of URLs used to track an action associated with a tile template.
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.
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.

Get a Specific Campaign for a Customer by Internal User ID and Campaign ID

Fetches a campaign that a user is eligible for by an internal user ID and a campaign ID.

Note that this is a V2 endpoint. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
ad_campaign_id Internal SessionM identifier for campaign.
sections[] Controls which sections of the campaign will appear. Possible values: progress includes user progress through campaign; behaviors includes all behaviors (achievements) in campaign; offers includes detailed deals request; and, redemptions includes customer redemptions.
filters[] Controls which campaigns appear for associated customer. Possible values: ineligible includes only campaigns customer is ineligible for; eligible includes just campaigns customer is eligible for; and, all includes all active campaigns, ineligible and eligible.
creatives[] Controls which creatives are shown. Leaving parameter blank removes the creative section. Possible values: promotion includes promotion section if available; and tile includes tile section if available.
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

{
  "status": "ok",
  "campaign": {
    "campaign_id": 11,
    "campaign_permalink": "9f86dafb-b999-4b61-8c71-59d9d45628f2",
    "creative": {
      "promotion": {
        "type": "internal_full_page",
        "html_payload": "http://ads.host/apps/xyz130d6fdeb9ef1af877dae1d3b749e842727543cc5/users/5a296e48-d458-11e7-9958-5691328254fd/ads/11"
      }
    },
    "ends_at": "2017-12-01 16:22:41",
    "name": "Campaign 11",
    "opt_in_ends_at": "2017-12-01 16:22:41",
    "opt_in_starts_at": "2017-11-27 16:22:41",
    "opted_in": true,
    "qualified": true,
    "starts_at": "2017-11-27 16:22:41",
    "status": "completed"
  }
}


Most of the attributes of this Campaign object are described in the Response Attributes for Campaign table. However, the creative object - which resides within the campaign object - does contain a promotion object that is detailed in the following table:

Response Attributes for Promotion

Attribute Type Description
type string Indicates what kind of ad the promotion is. Typically, ads being returned in the API are tiles, internal_tile.
html_payload string URL into SMP platform that renders tile.
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.

Fetches a campaign that a user is eligible for by ID (internal or external) and campaign (permalink or ID).

Note that these are V2 endpoints. You can consult Implementation Notes for Retrieving Campaigns Using V2 APIs for additional implementation details.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v2/apps/:api_key/users/:user_id/external/campaigns/:permalink
GET /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:permalink
GET /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 Campaign permalink that can be customer-defined or auto-generated.
ad_campaign_id Internal SessionM identifier for campaign.
sections[] Controls which sections of the campaign will appear. Possible values: progress includes user progress through campaign; behaviors includes all behaviors (achievements) in campaign; offers includes detailed deals request; and, redemptions includes customer redemptions.
filters[] Controls which campaigns appear for associated customer. Possible values: ineligible includes only campaigns customer is ineligible for; eligible includes just campaigns customer is eligible for; and, all includes all active campaigns, ineligible and eligible.
creatives[] Controls which creatives are shown. Leaving parameter blank removes the creative section. Possible values: promotion includes promotion section if available; and tile includes tile section if available.
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
  "behaviors": {
    "super user 12": {
      "event_name": "Event 12",
      "type": "count",
      "points": 5,
      "max_times_repeatable": null,
      "max_times_repeatable_per_period": 1,
      "period": 86400,
      "min_time_between_events": null,
      "consecutive": false,
      "achieved": 0,
      "current_count": 0,
      "total_count": 1
    },
    "participation challenge": {
      "event_name": "entry",
      "type": "count",
      "points": 0,
      "max_times_repeatable": 1,
      "max_times_repeatable_per_period": 1,
      "period": 7776000,
      "min_time_between_events": null,
      "consecutive": false,
      "achieved": 0,
      "current_count": 0,
      "total_count": 1
    }
  },
  "campaign_id": 16,
  "campaign_permalink": "d615678c-d458-11e7-8ac1-c27a328254fd",
  "ends_at": "2017-12-01 16:26:09",
  "name": "Campaign 16",
  "offers": [
  {
    "offer_id": 1,
    "name": "Offer 1 gift card",
    "type": "deal",
    "total_available": 100,
    "deal": {
      "percent": 10.0,
      "offer_type_id": "percent_discount",
      "id": "0c7af47e-12ef-4474-a0b7-3540948783bb",
      "root_offer_id": "d616c71c-d458-11e7-9903-c0c9328254fd",
      "retailer_id": "d616ee2c-d458-11e7-9d46-e185377754fd",
      "offer_text": [
        {
          "id": "0c7af47e-12ef-4474-a0b7-3540948783bb",
          "offer_id": "ff4b3d3c-8185-48b7-8014-dd03c2c55864",
          "culture": "en",
          "title": "Test for Offer796899",
          "description": "Testing Issue Offer",
          "terms": "Don't panic!"
        }
      ],
      "valid_after_end_date": true,
      "value_after_end_date": null,
      "start_date": "2017-11-28T16:26:10+0000",
      "end_date": "2017-11-29T16:26:10+0000",
      "validity_period": 1,
      "validity_unit": "day",
      "points": 200,
      "buy_count": 0,
      "max_recurrence": 1,
      "item_price_affinity": 0,
      "web_redeem": false,
      "quantity": 0,
      "reward_store": false,
      "offer_catalog_restrictions": null,
      "offer_purchase_restrictions": null,
      "offer_redemption_restrictions": null,
      "offer_location_restrictions": null,
      "offer_media": [
        {
          "id": "d617153c-d458-11e7-9ad9-8d08328254fd",
          "uri": "http://www.example.com",
          "category_id": "d617153c-d458-11e7-9ad9-8d08328254fd",
          "category_name": null,
          "content_type": 1,
          "culture": "en"
        }
      ]
    }
  },
  {
    "offer_id": 2,
    "name": "referrer points",
    "type": "trigger",
    "total_available": 1000000000
  }
],
  "opt_in_ends_at": "2017-12-01 16:26:09",
  "opt_in_starts_at": "2017-11-27 16:26:09",
  "qualified": true,
  "starts_at": "2017-11-27 16:26:09",
  "status": "qualified"
}


This object is detailed in the following tables:

Response Attributes for Behaviors

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.
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.
consecutive boolean Indicator wether events need to happen on consecutive days
achieved integer Total times the action has been completed by a given customer.
current_count integer Event count towards completing the action.
total_count integer Event count required for completing the action.

Response Attributes for Campaigns

Attribute Type Description
campaign_id integer Campaign identifier internal to SessionM.
campaign_permalink string Permanent, static hyperlink for campaign.
ends_at datetime Date and time at which campaign becomes inactive.
name string Name of campaign.
offers array For more information, see the Response Attributes for Offers table below.
opt_in_ends_at datetime Opt-in ending date.
opt_in_starts_at datetime Opt-in starting date.
qualified boolean Current customer qualification for campaign - after domain call. For example, false can result from targeting that tags the customer and targeted away from the campaign.
starts_at datetime Date and time at which campaign becomes active.
status string Current status of the campaign for the given customer - after domain call. For example, "completed" indicates that all behaviors in the campaign being completed.

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_available integer Limit on how many times the offer can be issued in total.
deal object For more information, see Response Attributes for Deal table below.

Response Attributes for Deal

Attribute Type Description
percent decimal Discount amount when offer type is percent_discount.
offer_type_id string Can be fixed_amount_discount or percent_discount; not sure if there are more types.
id string ID of the offer (GUID string).
root_offer_id string ID of the parent offer (GUID string).
retailer_id string ID of the retailer in the Connect database (similar to SessionM organization). Also a GUID.
offer_text array See Response Attributes for Offer Text table below.
valid_after_end_date boolean If true, the offer can still be redeemed by a customer after the end date.
value_after_end_date datetime New offer value once it expires. For example, it may still be redeemable but gives 5% discount instead of 10%.
start_date datetime Start of the period during which the offer may be redeemed.
end_date datetime End of the period during which the offer may be redeemed.
validity_period integer Period of time in days/hours/years. (See validity_unit.) The offer is valid once started.
validity_unit string Unit measuring the validity period (days, years, etc.).
points integer integer
max_recurrence integer Maximum number of times this offer can recur.
item_price_affinity integer Specifies whether the awarded item(s) are the higher-priced items, or the lower-priced items. 0 - Lowest priced items 1 - Highest priced items.
web_redeem boolean Can the offer be redeemed via the retailer’s web site.
quantity integer Number of offers remaining which can be purchased.
offer_catalog_restrictions array Catalog restriction objects that define what catalog items are eligible for the offer.
offer_purchase_restrictions array Purchase restriction objects that define when and where the purchase needs to be made to be eligible.
offer_redemption_restrictions array Redemption restriction objects.
offer_location_restrictions array Location restriction objects.
*offer_media" array See Response Attributes for Offer Media table below.

Response Attributes for Offer Text

Attribute Type Description
id string GUID of this object.
offer_id string GUID of the offer it belongs to.
culture string Language or locale.
title string Title of the offer.
description string Description of the offer.
terms string Fine print governing offer.

Response Attributes for Offer Media

Attribute Type Description
id string ID of the offer group.
uri string URI of the media object.
category_id string ID of the category for which this media item belongs.
category_name string Name of the media object’s category.
content_type integer Numeric representation of the type of media. (Not to be confused with MIME type.) Values include: 1 - Image; 2 - Video; 4 - Audio; 5 - Web Link.
culture string The culture for which the requested offers should be returned. Defaults to “en” if not provided.
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.

Implementation Notes for Retrieving Campaigns Using V2 APIs

As you work with any of the V2 endpoints that get campaigns via V2 routes, consider some important implementation details.

Base controller for any of the Campaigns V2 APIs: /dev/core1/app/controllers/priv/v2/users/campaigns/base_controller.rb

Controller for the show and index routes: /dev/core1/app/controllers/priv/v2/users/campaigns_controller.rb (edited)

Endpoints that show and index offer a few different kinds of parameters:

Sections*

Filters:

Creatives:

These parameters are defined in the "Endpoint Parameters" sections of Get all active campaigns eligible for a customer, Get a specific campaign for a customer by internal user ID and campaign ID, and Get a specific campaign for a customer by ID and either campaign permalink or ID.

Sample Curl:

curl -g -H 'Content-Type:application/json' -u ':redacted' 'https://api-acme.stg-sessionm.com/priv/v2/apps/64f15f67f03de170fb01dd41c0a4321e5d5dfc01/users/c4ce8a2e-bd20-11e8-83a5-ef4eff57e974/campaigns/565?sections[]=behaviors&sections[]=progress,&sections[]=offers&sections[]=redemptions'

Retrieving Campaigns

This family of APIs allows you to:

Get All Active Campaigns

Fetches all active campaigns within a specific platform implementation without having to provide any user-specific data.

Endpoints

This method offers the following endpoint:

▿ REST Endpoint

GET /v1/apps/:api_key/campaigns


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 campaigns array, as shown below:

▿ JSON Response

{
  "status": "ok",
  "campaigns": [
    {
      "id": 367,
      "external_id": "cc8b6c38-b5c8-11e7-9082-dc7a60cca317",
      "name": "Campaign Example",
      "starts_at": "2017-10-01T18:59:00Z",
      "ends_at": "2018-02-28T19:59:00Z",
      "status": "draft",
      "weight": 5,
      "total_budget": 0,
      "ssap_name": "10/20 test 11",
      "reporting_ends_at": "2018-04-14T18:59:00Z",
      "campaign_type": "messaging",
      "metadata": {"campaign_version": 2},
      "template": "messaging",
      "targeting": {
        "$and": [
          {
            "user.tags": {
              "$in": ["my_tag_to_target_user"]
            }
          },
          {
            "user.tags": {
              "$not": {
                "$in": ["my_tag_to_target_away_from_user"]
              }
            }
          }
        ]
      },
      "qualify_tag": "my_tag_to_target_user",
      "disqualify_tag": "my_tag_to_target_away_from_user"
    }
  ]
}


This object is detailed in Response Attributes for Campaign 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 Missing campaign data.
not_found Parent model not found.
validation Validation error.

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

Get Information on a Specific Campaign

Fetches a specific campaign within a platform implementation, including its associated information without having to provide any user-specific data. Individual campaigns can be specified using either the campaign_id or permalink parameters.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/campaigns/:campaign_id/info
GET /priv/v1/apps/:api_key/external/campaigns/:permalink/info  


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM identifier for campaign.
api_version Internal parameter that supports API versioning.
permalink Campaign permalink that can be customer-defined or auto-generated.
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

{
  "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"
  }  
}


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.
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.

Campaigns Management API

Campaign management objects enable developers to program an entire campaign via APIs. They are very useful for partners or SessionM integration engineers tasked with setting up a campaign, especially when they need to extract, transform and load data (ETL). The APIs provide a variety of management capabilities powered by endpoints that create, update, delete the model required to make a full campaign.

The following terms are critical to understanding campaigns and the objects they comprise:

The entities described above constitute a campaign hierarchy. Together, they represent the core types of data the platform offers for the creation and maintenance of campaigns, including the ETL activities required at the beginning of an implementation. This diagram depicts how Campaign Management objects interrelate and what kinds of data they contain:

Campstruct

At the top of the diagram is the primary campaign object, AdCampaign. It stores basic information about the campaign, such as its name, owner, and the dates it begins and ends. This campaign object has three children - the ad bundle, the line item, and any achievements defined for the campaign.

To the far left of the diagram is the AdBundle object, which handles targeting information on the campaign level. This targeting data is shown in the related database table with AdTarget attributes for state, gender, and a tag.

Directly below AdCampaign is the AdLineItem object, which is a legacy object that serves only one function - to be a container for the creative group. That group object, called AdGroup in the database, holds message level targeting information. Like the AdBundle, it too owns a related database table with AdTarget attributes; in this case, attributes for zip, platform, and a tag. The final child of AdLineItem is AdUnit, is the actual creative, or message, being delivered for the campaign. It contains delivery option information such as a scheduled delivery date or a specific achievement trigger. In addition, the AdUnit can contain a message template, messaging provider information, and an image URL for any graphic advertisements.

And, finally, to the far right of the diagram, you can see the Achievements object, which contains any of the behaviors that must be met in order to trigger the outcomes offered by the campaign.

The Campaigns Management API provides a collection of APIs that correspond to the following areas of focus:

Retrieving Campaigns for Management

This family of APIs allows you to:

Get All Campaigns

Fetches all campaigns within a specific platform implementation.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/campaigns


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
limit Number of campaigns to return. Default is 10.
page The 1-based page number.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an array of campaign objects, which is shown and detailed in the response sample and in the Response Attributes for Campaign 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 Missing campaign data.
not_found Parent model not found.
validation Validation error.

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

Get a Campaign

Fetches a campaign by either campaign ID or permalink.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id
GET /priv/v1/apps/:api_key/management/external/campaigns/:permalink


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM identifier for campaign.
permalink Campaign permalink that can be customer-defined or auto-generated.
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, which is shown and detailed in the response sample and in the Response Attributes for Campaign 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 Missing campaign data.
not_found Parent model not found.
validation Validation error.

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

Get a Complete Hierarchy for a Campaign

Fetches a campaign's complete navigation hierarchy, detailing all of the containers, creative groups, and creatives in the campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/navigation


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM 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 campaign object, as shown below:

▿ JSON Response

{
    "status": "ok",
    "campaign": {
        "id": 730,
        "name": "Campaign Example 730",
        "status": "live",
        "starts_at": "2021-12-31T05:00:00Z",
        "ends_at": "2022-01-04T05:00:00Z",
        "line_items": [
            {
                "id": 726,
                "name": "line item for campaign 730",
                "status": "draft",
                "starts_at": "2021-12-31T05:00:00Z",
                "ends_at": "2022-01-04T05:00:00Z",
                "creative_groups": [
                    {
                        "id": 2331,
                        "name": "new creative group",
                        "status": "draft",
                        "starts_at": "2020-08-12T17:45:48Z",
                        "ends_at": "2020-09-12T17:45:48Z",
                        "creatives": [
                            {
                                "id": 2557,
                                "name": "Email File Export Test 1",
                                "status": "draft"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}


This object contains the core components of a campaign hierarchy, including the campaign itself along with its container, creative group, and creative. For more information on each object, see the following sections:

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 Missing campaign data.
not_found Parent model not found.
validation Validation error.

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

Managing Campaign Behaviors

This family of APIs allows you to:

Get All Behaviors for a Campaign

Fetches an array of all behaviors defined for a campaign. For a comprehensive view of a campaign, see Get Information on a Campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/behaviors


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM ad campaign ID.
Request Object

Not applicable.

Response Object 1

This response is for a behavior triggered by a custom event and drops a tag as its outcome. It represents a single behavior named “custom event behavior” that actually consists of 2 achievements, the goal (id 2475) and the composite(id 2476). The composite achievement duplicates the goal achievement data in its goals array.

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

▿ JSON Response

{
    "behaviors": [
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "max_times_achievable": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_year": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000
            },
            "errors": {},
            "id": 2475,
            "name": "MMC-72b1c697-7090-4aef-9f6e-4f0a7e24cd15",
            "points": 0,
            "tags": null
        },
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "goals_csv_data": "2475,1,true,0,1,false\n",
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "period": 86400,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "data": {
                                    "consecutive": false,
                                    "eligible_spend": null,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_year": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000
                                },
                                "errors": {},
                                "event_count": 1,
                                "id": 2475,
                                "name": "MMC-72b1c697-7090-4aef-9f6e-4f0a7e24cd15",
                                "points": 0,
                                "tags": null
                            }
                        }
                    ]
                }
            ],
            "id": 2476,
            "name": "custom event behavior",
            "outcomes": [],
            "points": 0,
            "tags": "custom_behavior_completed"
        }
    ],
    "status": "ok"
}


This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors table.

Response Object 2

This response is for a purchase behavior that requires the user to purchase any 3 items and award 10 points as its outcome.

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

▿ JSON Response


{
    "behaviors": [
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "max_times_achievable": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_year": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000
            },
            "errors": {},
            "id": 2477,
            "name": "MMC-07431719-e3bd-46e9-8f72-f7a6bead9ceb",
            "points": 0,
            "tags": null
        },
        {
            "data": {
                "consecutive": false,
                "eligible_spend": null,
                "goals_csv_data": "2477,1,true,0,1,false\n",
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "period": 86400,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "data": {
                                    "consecutive": false,
                                    "eligible_spend": null,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_year": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000
                                },
                                "errors": {},
                                "event_count": 1,
                                "id": 2477,
                                "name": "MMC-07431719-e3bd-46e9-8f72-f7a6bead9ceb",
                                "points": 0,
                                "tags": null
                            }
                        }
                    ]
                }
            ],
            "id": 2478,
            "name": "purchase event test",
            "outcomes": [
                {
                    "account_id": null,
                    "created_at": "2017-10-18T21:00:48Z",
                    "id": 97,
                    "model_id": 87,
                    "model_type": "Offer",
                    "organization_id": 13,
                    "updated_at": "2017-10-18T21:00:48Z"
                }
            ],
            "points": 10,
            "tags": ""
        }
    ],
    "status": "ok"
}


This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors table.

Response Object 3

This response is for a purchase behavior that requires the user to purchase any item. The response also demonstrates the start/end time behavior restriction. For more information, see the event_filters object in the response below.

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

▿ JSON Response

{
    "status": "ok",
    "behaviors": [
        {
            "id": 2506,
            "name": "MMC-2aef35f7-bff9-4df4-9e26-196816179f4b",
            "points": 0,
            "tags": null,
            "data": {
                "result_trigger": null,
                "eligible_spend": null,
                "precise_event_count": null,
                "unit_precision": null,
                "min_time_between_events": null,
                "min_time_between_events_count": 1,
                "period": 7776000,
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "max_times_achievable_per_month": null,
                "max_times_achievable_per_year": null,
                "consecutive": false
            },
            "errors": {}
        },
        {
            "id": 2507,
            "name": "goal start/end test",
            "points": 0,
            "tags": "",
            "data": {
                "result_trigger": null,
                "eligible_spend": null,
                "precise_event_count": null,
                "unit_precision": null,
                "goals_csv_data": "2506,1,true,0,1,false\n",
                "period": 86400,
                "max_times_achievable": null,
                "max_times_achievable_per_period": null,
                "min_time_between_events": null,
                "consecutive": false,
                "use_same_period": false
            },
            "errors": {},
            "goal_groups": [
                {
                    "goal_count": 1,
                    "goals": [
                        {
                            "achievement": {
                                "id": 2506,
                                "name": "MMC-2aef35f7-bff9-4df4-9e26-196816179f4b",
                                "points": 0,
                                "tags": null,
                                "data": {
                                    "result_trigger": null,
                                    "eligible_spend": null,
                                    "precise_event_count": null,
                                    "unit_precision": null,
                                    "min_time_between_events": null,
                                    "min_time_between_events_count": 1,
                                    "period": 7776000,
                                    "max_times_achievable": null,
                                    "max_times_achievable_per_period": null,
                                    "max_times_achievable_per_month": null,
                                    "max_times_achievable_per_year": null,
                                    "consecutive": false
                                },
                                "errors": {},
                                "event_count": 1,
                            }
                        }
                    ]
                }
            ],
            "outcomes": []
        }
    ]
}


This behaviors array object is detailed in the tables describing the behaviors array that is returned when creating behaviors in batch for a campaign. You can consult all of the tables in that section, starting with the Response Attributes for Behaviors 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.

Create Behaviors in Batch for a Campaign

Creates behaviors in batch for a campaign. The request object creates a campaign behavior triggered by a custom event (my_custom_event). The request then awards an offer and tags the user (custom_behavior_completed) as its outcomes.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/management/campaigns/:campaign_id/behaviors/_batch


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM ad campaign ID.
Request Object

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

▿ JSON Request

{
   "behaviors":[
      {
          "name": "custom event behavior - campaign 730",
          "tags": "custom_behavior_completed",
          "data": {
              "period": 86400,
              "max_times_achievable": null,
              "use_same_period": false
          },
          "goal_groups": [
              {
                  "goals": [
                      {
                          "achievement": {
                              "name": "goal achievement for custom event behavior - campaign 730",
                              "internal_event_name": "my_custom_event",
                              "event_count": 1,
                              "data": {
                                  "period": 7776000,
                                  "max_times_achievable": null,
                                  "max_times_achievable_per_period": null,
                                  "min_time_between_events": null,
                                  "min_time_between_events_count": 1,
                                  "consecutive": false
                              }
                          }
                      }
                  ]
              }
          ],
          "outcome_config":[
            {
               "deal":{
                  "id": "514dafae-14ab-4104-b4da-3b2ad08f10d5"
               }
            }
         ]
      }
   ]
}


This object is detailed in the following table:

Request Attributes for Behaviors

Attribute Type
Required/Optional
Description
name string
required
Name of the behavior. Also serves as the name of the composite achievement.
tags string
optional
Tag - or list of tags - to be dropped on the customer when the behavior is completed. Multiple tags must be separated with a “\n”; for example, “tag1\ntag2\ntag3”)
data object
required
Configuration of the composite achievement. For more information, see the Request Attributes for Data table below.
goal_groups array
required
Goals (goal achievements) can be organized into groups - each with multiple goals. To complete the composite achievement, the customer needs to complete each of the groups. Use "AND" logic between groups and between goals in a group. For example, a simple behavior with one composite and one goal would have 1 goal group with 1 goal. The goal_groups array contains a goals array, which contains an achievement object. For more information, see the Request Attributes for Achievement table below.
outcome_config array
???
Array of outcome objects that can be an offer (deal object) or a message (ad unit object). The deal object which has an id attribute for the ID of an offer from the Offers Module.

Request Attributes for Data

Attribute Type
Required/Optional
Description
eligible_spend boolean
optional
Designates a special achievement type.
period integer
optional
Value in seconds used by other parameters that define time-bound rules. For example, if max_times_achievable_per_period is set to 3 and period to 3600, the goal’s outcome can be earned a maximum 3 times in 1 hour.
*min_time_between_events integer
optional
Minimum time - in seconds - to throttle the events counting towards the achievement.
*min_time_between_events_count integer
optional
Describes the maximum event rate and is only taken into account when min_time_between_events is not nil. For example if min_time_between_events = 1 day and min_time_between_events_count = 2, then no more than 2 event occurrences will be taken into account in a single day.
max_times_achievable integer
optional
Stipulates how many times a customer can achieve the outcome associated with the behavior.
*max_times_achievable_per_period integer
optional
Stipulates how many times a customer can achieve the outcome associated with the behavior in a defined period of time.
*max_times_achievable_per_month integer
optional
Stipulates how many times a customer can achieve the outcome associated with the behavior in a month.
*max_times_achievable_per_year integer
optional
Stipulates how many times a customer can achieve the outcome associated with the behavior in a year.
min_time_between_events integer
optional
Minimum time - in seconds - to throttle the events counting towards the achievement.
consecutive boolean
optional
Controls whether events must occur evenly for consecutive days set by event_count.
use_same_period boolean
optional
All behavior goals must be completed in the same timeframe.

Request Attributes for Achievement

Attribute Type
Required/Optional
Description
name string
required
Name of the custom event behavior goal.
internal_event_name string
optional
Name of the custom event to trigger the goal achievement.
event_count integer
optional
Number of times the event must be sent to trigger the achievement.
data object
required
Configuration of the composite achievement. For more information, see the Request Attributes for Data table above.
Response Object

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

▿ JSON Response

{
   "status":"ok",
   "behaviors":[
      {
         "id":2480,
         "name":"New behavior",
         "points":0,
         "tags":"my_tag_to_target_away_from_user",
         "data":{
            "eligible_spend":null,
            "goals_csv_data":"2479,1,false,0,0,false\n",
            "period":86400,
            "max_times_achievable":1,
            "max_times_achievable_per_period":null,
            "min_time_between_events":null,
            "consecutive":false,
            "use_same_period":false
         },
         "errors":{

         },
         "goal_groups":[
            {
               "goal_count":0,
               "goals":[
                  {
                     "achievement":{
                        "id":2479,
                        "name":"MMC-offer_issued",
                        "points":0,
                        "tags":null,
                        "data":{
                           "eligible_spend":null,
                           "min_time_between_events":null,
                           "min_time_between_events_count":1,
                           "period":86400,
                           "max_times_achievable":1,
                           "max_times_achievable_per_period":null,
                           "max_times_achievable_per_month":null,
                           "max_times_achievable_per_year":null,
                           "consecutive":false
                        },
                        "errors":{
                        },
                        "event_count":1,
                     }
                  }
               ]
            }
         ],
         "outcomes":[
            {
               "account_id":null,
               "created_at":"2020-08-13T15:51:52Z",
               "id":357,
               "model_id":120,
               "model_type":"Offer",
               "organization_id":13,
               "updated_at":"2020-08-13T15:51:52Z"
            }
         ]
      }
   ]
}


This object is detailed in the following table:

Response Attributes for Behavior

Attribute Type Description
id integer Database ID.
name string Name of the behavior. Also serves as the name of the composite achievement.
tags string Tag - or list of tags - to be dropped on the customer when the behavior is completed. Multiple tags must be separated with a “\n”; for example, “tag1\ntag2\ntag3”).
points integer Number of points associated with behavior.
data object See the Response Attributes for Data (Achievement) table below.
errors object Contains error code, if any. For example: "errors":{"code":"goal data is invalid"}.
goal_groups array Contains a goal group object, which is detailed in the Response Attributes for Goal Group table below.
outcomes array Contains outcome objects which are detailed in the Response Attributes for Outcomes table below.

Response Attributes for Data (Achievement)

Attribute Type Description
goals_csv_data string An auto generated field that is used internally. Provides configuration by which the composite finds its goal groups and goals.
period integer Value in seconds used by other parameters that define time-bound rules. For example, if max_times_achievable_per_period is set to 3 and period to 3600, the goal’s outcome can be earned a maximum 3 times in 1 hour.
max_times_achievable integer Number of times the outcome for a behavior can be achieved.
max_times_achievable_per_period integer Number of times the outcome for a behavior can be achieved in a specific time period.
max_times_achievable_per_month integer Number of times the outcome for a behavior can be achieved in a specific month.
max_times_achievable_per_year integer Number of times the outcome for a behavior can be achieved in a year.
min_time_between_events integer Minimum time - in seconds - to throttle the events counting towards the achievement.
*min_time_between_events_count integer Describes the maximum event rate and is only taken into account when min_time_between_events is not nil. For example if min_time_between_events = 1 day and min_time_between_events_count = 2, then no more than 2 event occurrences will be taken into account in a single day.
consecutive boolean Controls whether events must occur evenly for consecutive days set by event_count.
eligible_spend boolean Designates a special achievement type.
use_same_period boolean All behavior goals must be completed in the same timeframe.

Response Attributes for Goal Group

Attribute Type Description
goal_count integer Number of goal objects in the goals array.
goals array Contains goal objects, each of which contains achievement objects. See the Response Attributes for Achievement table below.

Response Attributes for Achievement

Attribute Type Description
id integer Database identifier.
name string Name of the custom event behavior goal.
tags string Tag - or list of tags - to be dropped on the customer when the behavior is completed. Multiple tags must be separated with a “\n”; for example, “tag1\ntag2\ntag3”).
points integer Number of points associated with behavior.
data object See the Response Attributes for Data (Achievement) table above.
errors object Contains error code, if any. For example: "errors":{"code":"goal data is invalid"}.
event_count integer Number of times the event must be sent to trigger the achievement.

Response Attributes for Outcomes

Attribute Type Description
account_id integer ID of SessionM Platform account that created the outcome.
created_at Datetime Timestamp for when the object was created.
id integer ID of the outcome object for this specific achievement.
model_id integer ID of the object describing what the actual outcome is.
model_type string Type of the actual outcome model. Can be one of following: “offer” - if the outcome awards points or issues an offer; “AdUnit” - if the outcome sends a message; or “EventOutcome” - if the outcome triggers another event.
organization_id integer ID of the organization that owns the object.
updated_at datetime Timestamp for when the object was last 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.

Managing Containers for Creative Groups

This family of APIs allows you to:

Create a Container for a Campaign

Creates a container in a campaign for creative groups.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/management/campaigns/:campaign_id/line_items


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM ad campaign ID.
Request Object

When this method runs, it passes in a request object that contains a line_item object which is shown below:

▿ JSON Request

{
  "line_item": {
      "name": "new line item",
      "starts_at": "2020-08-13 15:52:33 -0400",
      "ends_at": "2020-08-22 15:52:33 -0400",
      "status": "live"
  }
}


This object is detailed in the following table:

Request Attributes for Line Item

Attribute Type
Required/Optional
Description
name string
required
Name of line item (container) holding creative groups for a campaign.
starts_at datetime
required
Date and time when line item (container) becomes active. Should match campaign start date/time.
ends_at datetime
required
Date and time when line item (container) becomes inactive. Should match campaign end date/time.
status string
required
Status of line item (container). Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Line Items table.

Get All Containers for a Campaign

Fetches an array of containers (line item objects) for creative groups associated with a campaign by campaign ID. Note that there is only a single line item per campaign.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/campaigns/:campaign_id/line_items


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Internal SessionM ad campaign ID.
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
  "line_items": [
    {
        "campaign_id": 726,
        "starts_at": "2020-08-12T17:45:48Z",
        "ends_at": "2020-09-12T17:45:48Z",
        "id": 722,
        "name": "behaviors api test 2",
        "status": "live"
     }
   ],
   "status": "ok"
}


This array is detailed in the following table:

Response Attributes for Line Items

Attribute Type Description
campaign_id integer Identifier for parent campaign.
starts_at datetime Date and time when line item (container) becomes active. Should match campaign start date/time.
ends_at datetime Date and time when line item (container) becomes inactive. Should match campaign end date/time.
id integer ID of the object.
name string Name of line item (container).
status string Status of line item (container). Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
display_name string Additional descriptive information, if desired.
description string Additional descriptive information, if desired.
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 Parent model not found.
not_found Parent model not in same organization.

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

Get a Container by Container ID

Fetches a container (line item) for creative groups associated with a campaign by container ID.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/line_items/:line_item_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
line_item_id Identifier for the container (line item).
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a line_items array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Line Items 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
not_found Parent model not found.
not_found Parent model not in same organization.

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

Update a Container

Updates a container (line item) of creative groups.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/management/line_items/:line_item_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
line_item_id Identifier for the container (line item).
Request Object

When this method runs, it passes in a request object that contains a line_item object which is shown below:

▿ JSON Request

{
  "line_item": {
      "name": "updated new line item",
      "starts_at": "2020-08-13 15:52:33 -0400",
      "ends_at": "2020-08-22 15:52:33 -0400",
      "status": "live"
  }
}


This object is detailed in the following table:

Request Attributes for Line Item

Attribute Type
Required/Optional
Description
name string
required
Name of line item (container) holding creative groups for a campaign.
starts_at datetime
required
Date and time when line item (container) becomes active. Should match campaign start date/time.
ends_at datetime
required
Date and time when line item (container) becomes inactive. Should match campaign end date/time.
status string
required
Status of line item (container). Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
Response Object

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

▿ JSON Response

{
  "line_items": [
    {
        "campaign_id": 726,
        "starts_at": "2020-08-13 15:52:33 -0400",
        "ends_at": "2020-08-22 15:52:33 -0400",
        "id": 722,
        "name": "updated new line item",
        "status": "live"
     }
   ],
   "status": "ok"
}


This array is detailed in the following table:

Response Attributes for Line Items

Attribute Type Description
campaign_id integer Identifier for parent campaign.
starts_at datetime Date and time when line item (container) becomes active. Should match campaign start date/time.
ends_at datetime Date and time when line item (container) becomes inactive. Should match campaign end date/time.
id integer ID of the object.
name string Name of line item (container).
status string Status of line item (container). Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
display_name string Additional descriptive information, if desired.
description string Additional descriptive information, if desired.
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
argument_error Unknown line item (container) attributes test.
missing_data Missing line item (container) data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Delete a Container

Deletes a container (line item) of creative groups.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/management/line_items/:line_item_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
line_item_id Identifier for the container (line item).
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
  "status": "ok",
  "line_item": {
    "id": 372,
    "name": "Line Item Example[DELETED AT Oct 25, 2017 03:50 pm]",
    "status": "live",
    "campaign_id": 367,
    "starts_at": "2014-12-31T05:00:00Z",
    "ends_at": "2015-01-04T05:00:00Z"
  }
}


This object is detailed in the Response Attributes for Line Items 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
not_found Parent model not found.
not_found Parent model not in same organization.

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

Managing Creative Groups

This family of APIs allows you to:

Get All Creative Groups in a Container

Fetches all creative groups in a container (line item).

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/line_items/:line_item_id/creative_groups


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
line_item_id Identifier for the container (line item).
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
    "creative_groups": [
        {
            "ends_at": "2020-09-12T17:45:48Z",
            "id": 2326,
            "line_item_id": 722,
            "name": "Email File Export",
            "starts_at": "2020-08-12T17:45:48Z",
            "status": "live"
        },
        {
            "ends_at": "2020-09-12T17:45:48Z",
            "id": 2324,
            "line_item_id": 722,
            "name": "BEHAVIOR AD STAT",
            "starts_at": "2020-08-12T17:45:48Z",
            "status": "live"
        }
    ],
    "status": "ok"
}


This array is detailed in the following table:

Response Attributes for Creative Groups

Attribute Type Description
ends_at datetime Date and time when creative group becomes inactive. Should match campaign end date/time.
id integer ID of the object.
line_item_id integer Identifier for the parent object (container or line item).
name string Name of creative group.
starts_at datetime Date and time when creative group becomes active. Should match campaign start date/time.
status string Status of creative group. Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
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 Parent model not found.
not_found Parent model not in same organization.

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

Get a Creative Group in a Container

Fetches a specific creative group in a container (line item).

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_group_id Identifier for the creative group.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups 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
not_found Parent model not found.
not_found Parent model not in same organization.

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

Create a Creative Group in a Container

Creates creative groups for a container (line item).

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/management/line_items/:line_item_id/creative_groups


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
line_item_id Identifier for the container (line item).
Request Object

When this method runs, it passes in a request object that contains a creative_group object which is shown below:

▿ JSON Request

{
  "creative_group": {
    "name":"Group Name",
    "status":"live",
    "starts_at":"2014-12-31T05:00:00Z",
    "ends_at":"2015-01-04T05:00:00Z"}
}


This object is detailed in the following table:

Request Attributes for Creative Group

Attribute Type
Required/Optional
Description
name string
required
Name of creative group.
status string
required
Status of creative group. Same as campaign status (“draft,” “inreview,” “live,” “paused,” or “completed”). It needs to be "live" in order for creatives that it contains to be live.
starts_at datetime
required
Date and time when creative group becomes active. Should match campaign start date/time.
ends_at datetime
required
Date and time when creative group becomes inactive. Should match campaign end date/time.
display_name string
optional
Additional descriptive information, if desired.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups 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
argument_error Unknown creative group attributes test.
missing_data Missing creative group data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Update a Creative Group in a Container

Updates a creative group for a container (line item).

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_group_id Identifier for the creative group.
Request Object

When this method runs, it passes in a request object that contains a creative_group object which is shown below:

▿ JSON Request

{
  "creative_group": {
    "name":"Updated Group 3",
    "ends_at":"2015-02-04T05:00:00Z"}
}


This object is detailed in the Request Attributes for Creative Groups table.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creative_groups array object, a sample for which is shown and detailed in the response sample and in the Response Attributes for Creative Groups table. The response would include the new values for any updated 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. The platform returns the following error messages for this method:

Code Reason
argument_error Unknown creative group attributes test.
missing_data Missing creative group data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Delete a Creative Group from a Container

Deletes a creative group from a container (line item).

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_group_id Identifier for the creative group.
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
  "status": "ok",
  "creative_group": {
    "id": 12,
    "name": "Updated Group 2[DELETED AT Jan 1, 2015 05:00 am]",
    "status": "live",
    "line_item_id": 12,
    "starts_at": "2014-12-31T05:00:00Z",
    "ends_at": "2015-02-04T05:00:00Z"
  }
}


This object is detailed in the Response Attributes for Creative Groups 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
not_found Parent model not found.
not_found Parent model not in same organization.

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

Managing Creatives

This family of APIs allows you to:

Get All Creatives for a Group

Fetches all creatives for a group.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id/creatives


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_group_id Identifier for the creative group.
Request Object

Not applicable.

Response Object

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

▿ JSON Response

{
    "creatives": [
        {
            "ad_type": "issue_audience_csv",
            "application_id": 36,
            "creative_group_id": 2326,
            "creative_type": "issue-audience-csv",
            "id": 2553,
            "issue_audience_csv": {
                "delivery_method": "scheduled",
                "issue_offer_date": "2020-08-13T01:21:48+00:00",
                "next_ad_type": "interstitial",
                "offer_ids": [],
                "orientation": "portrait",
                "portal_description": "Check out this ad!",
                "portal_icon": "/images/icon_starv1_94x94.png",
                "scheduled_delivery_date": "2020-08-15T01:21:48+00:00",
                "second_sn_audience_guid": "cddea1ae-dcb7-11ea-95db-a7d2986d963d",
                "template_id": "my_creative_template",
                "trigger_type": "standard"
            },
            "name": "Email File Export",
            "status": "draft"
        }
    ],
    "status": "ok"
}


Note that actual responses may vary based on message type. This array is detailed in the following table:

Response Attributes for Creatives

Attribute Type Description
ad_type string Internal type for the creative, including the following: "issue_audience_csv," for email file export; "issue_audience_csv_no_msg," for dummy message; "issue_bulk_offer," for bulk offer message; "audience_export," for any audience export (Cheetahmail, Airship); "messaging_platform," for external message; "email_message," for email message; and "push_message," for push notification.
ssap_name string Display name for the SessionM Platform.
application_id integer ID of application object. Required for scheduled messages. Usually ID of same application that provides API key and secret for API calls.
creative_group_id integer ID of the parent object.
creative_type string Internal subtype of creative, including the following: "issue-audience-csv," for email file export; "issue-audience-csv-no-msg," for dummy message; "issue-bulk-offer," for bulk offer message; "audience-export-airship," for Airship audience export; "audience-export-cheetah," for Cheetahmail audience export; "audience-export-s3," for AWS audience export; "audience-export-facebook," for Facebook audience export; "messaging-platform-external," for external message; "messaging-platform-email," for email message; and "messaging-platform-push," for push notification.
id integer ID of the object.
issue_audience_csv object Messaging platform object. Content varies with ad_type. For example, scheduled messages contain scheduling options, while triggered messages have an achievement_id for the behavior that triggers the message. This sample features "issue_audience_csv". For information, see the Response Attributes for Messaging Platform (Issue Audience CSV) table below.
name string Name of creative.
status string Defines whether the creative is "live," "paused," "draft," "inreview," or "completed." Should be “live” for this endpoint. Users can engage with only a live creative via actions such as sending messages and allowing display ads to be seen.
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 Parent model not found.
not_found Parent model not in same organization.

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

Get a Creative for a Group

Fetches a creative for a creative group.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

GET /priv/v1/apps/:api_key/management/creatives/:creative_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_id Identifier for the creative.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

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 Parent model not found.
not_found Parent model not in same organization.

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

Create a Creative for a Group

Creates a creative for a group.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v1/apps/:api_key/management/creative_groups/:creative_group_id/creatives


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_group_id Identifier for the creative group.

Request Object

When this method runs, it passes in a request object that contains a creative object which is shown below:

▿ JSON Request

{
    "creative": {
        "ad_type": "issue_audience_csv",
        "application_id": 36,
        "creative_type": "issue-audience-csv",
        "issue_audience_csv": {
            "delivery_method": "scheduled",
            "scheduled_delivery_date": "2020-08-15T01:21:48+00:00",
            "template_id": "my creative template"
        },
        "name": "Email File Export Test 1",
        "status": "draft"
    }
}


This object is detailed in the following table:

Request Attributes for Creative

Attribute Type
Required/Optional
Description
ad_type string
required
Internal type for the creative, including the following: "issue_audience_csv," for email file export; "issue_audience_csv_no_msg," for dummy message; "issue_bulk_offer," for bulk offer message; "audience_export," for any audience export (Cheetahmail, Airship); "messaging_platform," for external message; "email_message," for email message; and "push_message," for push notification.
application_id integer
required
ID of application object. Required for scheduled messages. Usually ID of same application that provides API key and secret for API calls.
creative_type string
required
Internal subtype of creative, including the following: "issue-audience-csv," for email file export; "issue-audience-csv-no-msg," for dummy message; "issue-bulk-offer," for bulk offer message; "audience-export-airship," for Airship audience export; "audience-export-cheetah," for Cheetahmail audience export; "audience-export-s3," for AWS audience export; "audience-export-facebook," for Facebook audience export; "messaging-platform-external," for external message; "messaging-platform-email," for email message; and "messaging-platform-push," for push notification.
issue_audience_csv object Messaging platform object. Content varies with ad_type. For example, scheduled messages contain scheduling options, while triggered messages have an achievement_id for the behavior that triggers the message. This sample features "issue_audience_csv". For more information, see the Request Attributes for Issue Audience CSV table below.
name string
required
Name of creative.
status string
required
Defines whether the creative is "live," "paused," "draft," "inreview," or "completed." Should be “live” for this endpoint. Users can engage with only a live creative via actions such as sending messages and allowing display ads to be seen.

Request Attributes for Issue Audience CSV

Attribute Type
Required/Optional
Description
delivery_method string
required
The way the message will be delivered; allowed values are “triggered” and “scheduled”.
scheduled_delivery_date datetime
required for scheduled messages
Timestamp for when the message will be delivered.
template_id string
required for some message types
GUUID for the message template. Note that what a template is, is different for different messages.
Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

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
argument_error Unknown creative attributes test.
missing_data Missing creative data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Update a Creative for a Group

Updates a creative for a group.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/management/creatives/:creative_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_id Identifier for the creative.
Request Object

When this method runs, it passes in a request object that contains a creative object which is shown and detailed in the request sample and in the two corresponding tables, "Request Attributes for Creative" and "Request Attributes for Issue Audience CSV".

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

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
argument_error Unknown creative attributes test.
missing_data Missing creative data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Delete a Creative from a Group

Deletes a creative from a group.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/management/creatives/:creative_id


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
creative_id Identifier for the creative.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a creatives array object, a sample for which is shown and detailed in the response sample and in the two corresponding tables, "Response Attributes for Creatives" and "Response Attributes for Messaging Platform (Issue Audience CSV)".

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 Parent model not found.
not_found Parent model not in same organization.

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

Updating Campaigns

Updates a campaign by campaign ID or permalink.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

PUT /priv/v1/apps/:api_key/management/campaigns/:campaign_id
PUT /priv/v1/apps/:api_key/management/external/campaigns/:permalink


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Campaign identifier internal to SessionM.
permalink Permanent, static hyperlink for campaign.

Request Object

When this method runs, it passes in a campaign object, as shown below:

▿ JSON Request

{
  "campaign": {
    "name":"Campaign Example - name change",
    "status":"live",
    "starts_at":"2021-12-31T05:00:00Z",
    "ends_at":"2022-01-04T05:00:00Z
  }
}  


This object is detailed in the following table:

Request Attributes for Campaign

Attribute Type
Required/Optional
Description
name string
required
Name of campaign. Must be unique.
status string
required
Defines whether the campaign is "live," "paused," "draft," "inreview," or "completed." Should be “live” for this endpoint. Users can engage with only a live campaign via actions such as triggering behaviors and receiving outcomes.
starts_at datetime
required
Timestamp when campaign becomes active.
ends_at datetime
required
Timestamp when campaign becomes inactive.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a campaign object, which is detailed in Response Attributes for Campaign 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
argument_error Unknown campaign attributes test.
missing_data Missing campaign data.
not_found Parent model not found.
not_found Parent model not in same organization.
validation Validation error.

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

Performing Campaign Domain Actions

Campaign domain actions programmatically force customers to progress through a sequence of campaign milestones without having to actually perform an action. Normally, these actions are written to the platform through live integrations, which include purchases, store visits, and custom events.

These actions are performed for a specific campaign by some combination of user IDs (internal or external) and campaign ID or permalink. The endpoints available with this API complete a campaign by earning all of the simple behaviors (goals) belonging to a composite behavior. Doing so earns the composite behavior of a given campaign.

Note: Once the campaign has already been completed - the behaviors have reached their frequency cap - it can’t be completed again.

Implementation Notes for Performing Campaign Domain Actions Using V2 APIs

As you work with any of the V2 endpoints that perform domain actions via V2 routes, consider some important implementation details.

Base controller for any of the Campaigns V2 APIs: /dev/core1/app/controllers/priv/v2/users/campaigns/base_controller.rb

Controller for the perform routes: /dev/core1/app/controllers/priv/v2/users/campaigns_controller.rb (edited)

Endpoints that perform domain actions offer a few different kinds of parameters:

Sections:

Filters:

Creatives:

These parameters are defined in the "Endpoint Parameters" section below.

Sample Curl:

curl -g -H 'Content-Type:application/json' -u ':redacted' 'https://api-acme.stg-sessionm.com/priv/v2/apps/64f15f67f03de170fb01dd41c0a4321e5d5dfc01/users/c4ce8a2e-bd20-11e8-83a5-ef4eff57e974/campaigns/565?sections[]=behaviors&sections[]=progress,&sections[]=offers&sections[]=redemptions'

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

POST /priv/v2/apps/:api_key/users/:user_id/campaigns/:ad_campaign_id/perform
POST /priv/v2/apps/:api_key/users/:user_id/external/campaigns/:permalink/perform
POST /priv/v2/apps/:api_key/external/users/:external_id/campaigns/:ad_campaign_id/perform
POST /priv/v2/apps/:api_key/external/users/:external_id/external/campaigns/:permalink/perform


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
ad_campaign_id Campaign identifier internal to SessionM.
permalink Permanent, static hyperlink for campaign that can be customer-defined or auto-generated.
sections[] Controls which sections of the campaign will appear. Possible values: progress includes user progress through campaign; behaviors includes all behaviors (achievements) in campaign; offers includes detailed deals request; and, redemptions includes customer redemptions.
filters[] Controls which campaigns appear for associated customer. Possible values: ineligible includes only campaigns customer is ineligible for; eligible includes just campaigns customer is eligible for; and, all includes all active campaigns, ineligible and eligible.
creatives[] Controls which creatives are shown. Leaving parameter blank removes the creative section. Possible values: promotion includes promotion section if available; and tile includes tile section if available.

Request Object

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

▿ JSON Request

{
  "domain": "complete_campaign"
}


This object is detailed in the following table:

Request Attributes for Domain

Attribute Type
Required/Optional
Description
domain string
required
The action this endpoint tells the platform to perform on the provided campaign and user ID (or list of IDs). In the request example, domain value is “complete_campaign”, which tells the platform to complete the campaign for the user (or users). Completing a campaign in this context means earning all the campaign behaviors - as if the user actually performed all the required actions to complete it.

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

{
  "status": "ok",
  "campaign": {
      "campaign_id": 401,
      "campaign_permalink": "7ecea43c-d478-11e7-97fa-26a9d64d3094",
      "ends_at": "2018-12-31 10:33:20",
      "name": "New Campaign",
      "qualified": false,
      "starts_at": "2017-11-28 05:34:20",
      "status": "completed"
  }
}


This object is detailed in Response Attributes for Campaign 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
not_available Unknown domain.
failed_to_perform Domain call was not successful.

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

Deleting Campaigns

Deletes a campaign by campaign ID or permalink.

Endpoints

This method offers the following endpoints:

▿ REST Endpoints

DELETE /priv/v1/apps/:api_key/management/campaigns/:campaign_id
DELETE /priv/v1/apps/:api_key/management/external/campaigns/:permalink


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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.
campaign_id Campaign identifier internal to SessionM.
permalink Permanent, static hyperlink 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 campaign object, which is detailed in Response Attributes for Campaign 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
not_found Parent model not found.
not_found Parent model not in same organization.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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=


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 support customer loyalty programs, including APIs for the following:

The sections below document these APIs.

Note that the bulk of the platform's loyalty API documentation resides in the Swagger libraries for the Offers, Incentives, Catalog and Transactions domains. For more information, consult your SessionM customer success contact.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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
optional
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>


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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>


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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>


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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>


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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


For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

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 transaction