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:

  • Consecutive count -- Number of lockout-eligible events that have happened in a row since the last lockout period.
  • Cumulative count -- Number of cumulative lockout-eligible events that have happened all time for the customer.
  • Lockout expiration -- Time at which lockout expires.
  • Lockout count resets -- Number of times lockout counts have been reset.
  • Lockout duration -- Duration of lockout in seconds.

Lockout policies are one implementation of the policy object. For example, for promo code lockout policies, the type is promo_code_lockout.

API Contingencies and Combinations:
Lockout policies return the lockout count for a customer/type pair. Therefore, you must create the customers prior to fetching the lockout counts for them. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
Lockout policies also work with objects from the Promo Codes APIs, limiting the number of invalid promo code entries a customer can make before getting locked out of the system.

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:

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

  • policy
  • player

These objects are shown below:

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

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

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

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