Customer Profile APIs

Create, retrieve, update and search standard customer profiles, and manage client-defined custom profile attributes.

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.

API Contingencies and Combinations:

While the standard profile contains a customer's pre-configured demographic metadata, the Custom Profile API allows you to add new client-defined attributes to the profile. The response object for this operation contains the custom profile, the attributes of which appear in the object's user_profile section. If you want to retrieve a list of these attributes, use the Model API to make the requisite GET request.

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

Create a standard profile
Confirm a standard profile via email
Retrieve a standard profile
Retrieve multiple standard profiles
Update a standard profile
Search for a standard profile

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 for Create a Standard Profile

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 for Create a Standard Profile

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 for Create a Standard Profile

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",
     "phone_numbers":
     [{
        "phone_number": "1234123123",
        "phone_type": "home",
        "preference_flags": ["primary"]
     }]
     "referral":
     {
        "referral_code": "JOHN-70A756",
     }
   }
}

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, male, f, female, x, non-binary, unknown, or u. When an invalid value is specified, the system creates a new user record and sets its gender to nil.
first_name	string optional	Customer's first name.
last_name	string optional	Customer's last name (surname).
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.
referral	object optional	Referral associated with customer. Submit this object when a customer is signing up with a referral code from another customer. For more information, see the Request Attributes for Referrals table.

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.

Request Attributes for Referrals

Attribute	Type Required/Optional	Description
referral_code	string optional	Referrer code associated with the customer who is referring the new user. The code must be associated with a customer in SessionM. An invalid code will result in an error.

Response Object for Create a Standard Profile

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, male, f, female, x, non-binary, unknown, or u. When an invalid value is specified, the system creates a new user record and sets its gender to nil.
dob	string	Customer's date of birth. Format is YYYY-MM-DD.
account_status	string	Deprecated.
auth_token	string	Deprecated.
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	Deprecated.
tier	string	Deprecated.
referrer_code	string	Auto-generated by SessionM for every customer. Code is a concatenation of the customer's first name and first letter of their last name, followed by 6-digit random string. If this data is not available, the system creates a random string. Referrer code will update when the first name, last name, or email address changes.
registered_at	datetime	Datetime user account was registered. Format is not configurable. Format is YYYY-MM-DD HH:MM:SS
suspended	boolean	Deprecated.
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 for Create a Standard Profile

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level 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.

Retrieve a Standard Profile

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

Endpoints for Retrieve a Standard Profile

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 for Retrieve a Standard Profile

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 for Retrieve a Standard Profile

Not applicable.

Response Object for Retrieve a Standard Profile

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 for Retrieve a Standard Profile

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 for Retrieve Multiple Standard Profiles

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 for Retrieve Multiple Standard Profiles

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 for Retrieve Multiple Standard Profiles

Not applicable.

Response Object for Retrieve Multiple Standard Profiles

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 for Retrieve Multiple Standard Profiles

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 for Update a Standard Profile

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 for Update a Standard Profile

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 for Update a Standard Profile

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 for Update a Standard Profile

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 for Update a Standard Profile

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.

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 for Search for a Standard Profile

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 for Search for a Standard Profile

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 for Search for a Standard Profile

Not applicable.

Response Object for Search for a Standard Profile

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 for Search for a Standard Profile

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.

API Contingencies and Combinations:

SessionM's Customer Profile APIs allow clients to change the attribute definitions that make up the customer profile record itself. The Custom Profile API allows you to add new attributes to the custom profile. If you want to retrieve a list of these attributes, use the Model API to make the requisite GET request.
Once the custom profile has been built, you can add a new customer to the system. While the custom profile contains customer-defined, custom attributes, the standard profile contains basic demographic metadata about a customer that is pre-configured with any installation of the SessionM Platform. Call the Standard Profile API to define a new customer and add a new standard profile to the platform. The response object for this operation includes the custom profile, which appears as custom attributes in the customer_profile section of the JSON response.
In addition to creating custom profile attributes, you can further define a custom profile by appending tags to it. Tags act as keyword classifiers and are associated with a counter to indicate the number of times a tag has been assigned. For more information, see the Tags API.
Other types of data that can be associated with a custom profile include data handled by the Events API.

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

Create a custom profile
Create an attribute in a custom profile
Retrieve a combined standard and custom profile
Retrieve a custom profile
Retrieve product recommendations associated with a custom profile
Update a combined standard and custom profile
Update a custom profile
Clear a custom profile attribute
Patch an attribute in a custom profile

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
Filter rules
Validation rules for strings
Validation rules for integers and decimals
Validation rules for dates and datetimes

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 for Create a Custom Profile

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 for Create a Custom Profile

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 for Create a Custom Profile

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 for Create a Custom Profile

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 for Create a Custom Profile

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 for Create an Attribute in a Custom Profile

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 for Create an Attribute in a Custom Profile

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 for Create an Attribute in a Custom Profile

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 for Create an Attribute in a Custom Profile

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 for Create an Attribute in a Custom Profile

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 for Retrieve a Combined Standard and Custom Profile

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/users/:user_id?user[user_profile]=true?expand_incentives=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 for Retrieve a Combined Standard and Custom Profile

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.
expand_incentives	Optional boolean that displays tier and point-related data. Syntax for parameter is expand_incentives=true.

Request Object for Retrieve a Combined Standard and Custom Profile

Not applicable

Response Object for Retrieve a Combined Standard and Custom Profile

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": {
        "id": "16565e86-d74f-11ea-8af9-8b7d3a6ff2a9",
        "external_id": "abc123",
        "opted_in": false,
        "activated": false,
        "proxy_ids": [],
        "identifiers": [
            {
                "external_id": "abc123",
                "external_id_type": null
            }
        ],
        "available_points": 0,
        "test_points": 0,
        "unclaimed_achievement_count": 0,
        "email": "test123@email.com",
        "dob": "2007-08-05",
        "created_at": "2020-08-05 19:08:46",
        "updated_at": "2020-08-05 19:08:49",
        "suspended": false,
        "last_name": "Test",
        "first_name": "Brendan",
        "registered_at": "2020-08-05 19:08:46",
        "profile_photo_url": "/images/account-neutral.png",
        "test_account": true,
        "account_status": "good",
        "tier": "Bronze",
        "tier_system": "Koalla Tier System - DO NOT PAUSE OR EDIT",
        "tier_points": 0,
        "next_tier_points": 1500,
        "tier_ends_value": 1500,
        "tier_entered_at": "2020-08-05 19:08:46",
        "tier_resets_at": "2021-08-05 19:08:46",
        "tier_details": {
            "tier_levels": [
                {
                    "id": "3e43bf1b-c6b9-4a04-83be-f39ea2da7340",
                    "tier_system_id": "e02dec3f-32f7-45f9-8c56-0b5ba5c03ec9",
                    "tier_level_id": "46cf8f24-8726-4787-90b9-463a561fd056",
                    "user_id": "16565e86-d74f-11ea-8af9-8b7d3a6ff2a9",
                    "join_date": "2020-08-05T19:08:46.63",
                    "tier_overview": {
                        "id": "46cf8f24-8726-4787-90b9-463a561fd056",
                        "tier_system_id": "e02dec3f-32f7-45f9-8c56-0b5ba5c03ec9",
                        "retailer_id": "bee4a5bb-a65f-4245-a8ef-ae6d38157858",
                        "name": "Bronze",
                        "rank": 0,
                        "status": 2
                    },
                    "next_tier_overview": {
                        "id": "f0e5f293-bc3b-49d5-9e55-03e05f25724b",
                        "tier_system_id": "e02dec3f-32f7-45f9-8c56-0b5ba5c03ec9",
                        "retailer_id": "bee4a5bb-a65f-4245-a8ef-ae6d38157858",
                        "name": "Silver",
                        "rank": 1,
                        "status": 2
                    },
                    "tier_progress": [
                        {
                            "rule_tree_id": "7aa17616-9ce4-4896-888d-f8cc39c962e3",
                            "rules": [
                                {
                                    "query_result": 0,
                                    "rule_id": "565d2010-0511-4135-bdb6-6385cb5292e1",
                                    "parent_id": "a63037ab-38e1-4167-ba37-e54963a66092",
                                    "tree_id": "7aa17616-9ce4-4896-888d-f8cc39c962e3",
                                    "rule_passed": false,
                                    "rule": {
                                        "discriminator": 2048,
                                        "target_balance": 1500,
                                        "comparison": 4,
                                        "id": "565d2010-0511-4135-bdb6-6385cb5292e1",
                                        "retailer_id": "bee4a5bb-a65f-4245-a8ef-ae6d38157858",
                                        "parent_id": "a63037ab-38e1-4167-ba37-e54963a66092",
                                        "rank": 0,
                                        "is_new": false,
                                        "constraints": [
                                            {
                                                "discriminator": 8,
                                                "point_accounts": {
                                                    "2a5dc275-2d4f-480b-a905-3886938c0bdb": "Koalla Tier Points"
                                                },
                                                "id": "a0debabf-1852-4843-aa18-951aacb99a32",
                                                "rule_id": "565d2010-0511-4135-bdb6-6385cb5292e1",
                                                "is_new": false,
                                                "rank": 0,
                                                "version": 0
                                            }
                                        ]
                                    },
                                    "discriminator": 2,
                                    "rule_tree_name": ""
                                },
                                {
                                    "rule_id": "a63037ab-38e1-4167-ba37-e54963a66092",
                                    "tree_id": "7aa17616-9ce4-4896-888d-f8cc39c962e3",
                                    "rule_passed": false,
                                    "rule": {
                                        "discriminator": 2,
                                        "id": "a63037ab-38e1-4167-ba37-e54963a66092",
                                        "retailer_id": "bee4a5bb-a65f-4245-a8ef-ae6d38157858",
                                        "rank": 0,
                                        "is_new": false,
                                        "constraints": []
                                    },
                                    "discriminator": 1,
                                    "rule_tree_name": ""
                                }
                            ]
                        }
                    ]
                }
            ],
            "point_account_balances": {
                "retailer_id": "bee4a5bb-a65f-4245-a8ef-ae6d38157858",
                "user_id": "16565e86-d74f-11ea-8af9-8b7d3a6ff2a9",
                "summary": {
                    "total_points": 0,
                    "life_time_points": 0
                },
                "details": [
                    {
                        "account_name": "Base Savings account",
                        "user_point_account_id": "",
                        "point_account_id": "5e0e3c09-c94f-45e3-a977-88c6e50c95c3",
                        "grouping_label": "",
                        "available_balance": 0,
                        "life_time_value": 0
                    },
                    {
                        "account_name": "Koalla Rewards Lifetime Tier Points",
                        "user_point_account_id": "",
                        "point_account_id": "472ce493-f9c3-4c1a-b07b-8f0a8742493a",
                        "grouping_label": "",
                        "available_balance": 0,
                        "life_time_value": 0
                    },
                    {
                        "account_name": "Koalla Rewards Spendable Points",
                        "user_point_account_id": "",
                        "point_account_id": "aed95ba6-b225-4fae-bbf2-a9cf4f827af0",
                        "grouping_label": "",
                        "available_balance": 0,
                        "life_time_value": 0
                    },
                    {
                        "account_name": "Koalla Rewards Partner Earned Spendable Points",
                        "user_point_account_id": "",
                        "point_account_id": "35bae3c3-5e57-429e-8a20-78ea85896ee0",
                        "grouping_label": "Partner Spendable",
                        "available_balance": 0,
                        "life_time_value": 0
                    },
                    {
                        "account_name": "Koalla Rewards Tier Points",
                        "user_point_account_id": "",
                        "point_account_id": "2a5dc275-2d4f-480b-a905-3886938c0bdb",
                        "grouping_label": "Spend",
                        "available_balance": 0,
                        "life_time_value": 0
                    },
                    {
                        "account_name": "NB 3-Tier Spend Account",
                        "user_point_account_id": "",
                        "point_account_id": "7f18e217-e10a-4b32-80d5-8ebeabe0f409",
                        "grouping_label": "Spend",
                        "available_balance": 0,
                        "life_time_value": 0
                    }
                ]
            }
        },
        "referrer_code": "BRENDANT-8B3AFC",
        "user_profile": {
            "Closest_Location": [],
            "Customer_Persona": [],
            "Dress_Size": [],
            "fav_music": [],
            "Favorite_Sports": [],
            "Favorite_Team": [],
            "Most_Frequent_Store": [],
            "Pant_Size": [],
            "Payment_Card_Hashed_IDs": [],
            "Primary_Boating_Use": [],
            "Private_Label_Credit_Card_Hashed_ID": [],
            "Push_Opt_In": [],
            "Shirt_Size": [],
            "Shoe_Size": [],
            "SMS_Opt_In": [],
            "SockSize": [],
            "family": [],
            "subscription": []
        }
    }
}

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 for Retrieve a Combined Standard and Custom Profile

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 for Retrieve a Custom Profile

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 for Retrieve a Custom Profile

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 for Retrieve a Custom Profile

Not applicable

Response Object for Retrieve a Custom Profile

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 for Retrieve a Custom Profile

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 for Retrieve Product Recommendations Associated with a Custom Profile

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 for Retrieve Product Recommendations Associated with a Custom Profile

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 for Retrieve Product Recommendations Associated with a Custom Profile

Not applicable

Response Object for Retrieve Product Recommendations Associated with a Custom Profile

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 for Retrieve Product Recommendations Associated with a Custom Profile

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 for Update a Combined Standard and Custom Profile

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 for Update a Combined Standard and Custom Profile

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 for Update a Combined Standard and Custom Profile

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 for Update a Combined Standard and Custom Profile

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 for Update a Combined Standard and Custom Profile

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 for Update a Custom Profile

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 for Update a Custom Profile

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 for Update a Custom Profile

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 for Update a Custom Profile

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 for Update a Custom Profile

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 for Clear a Custom Profile Attribute

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 for Clear a Custom Profile Attribute

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 for Clear a Custom Profile Attribute

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 for Clear a Custom Profile Attribute

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 for Clear a Custom Profile Attribute

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 for Patch an Attribute in a Custom Profile

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 for Patch an Attribute in a Custom Profile

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:

Test
Remove
Add
Replace
Move
Copy

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

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

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

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 for Patch an Attribute in a Custom Profile

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.

Was this page helpful?