Customer Profile APIs

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

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

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

Standard Profile API

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

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

• Create a standard profile
• Confirm a standard profile via email
• Retrieve a standard profile
• Retrieve multiple standard profiles
• Update a standard profile
• Delete 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

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Request Attributes for User

Request Attributes for Phone Numbers

Response Object

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

Consider the following sample:

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

Response Attributes for Identifiers

Response Attributes for Account Statuses

Response Attributes for Phone Numbers

Statuses and Errors

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

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

Retrieve a Standard Profile

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

Not applicable.

Response Object

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

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

Statuses and Errors

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

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

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

Retrieve Multiple Standard Profiles

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

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/users/?user_ids[]=:user_id1&user_ids[]=:user_id2&show_identifiers=true

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

Endpoint Parameters

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

Request Object

Not applicable.

Response Object

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

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

Statuses and Errors

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

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

Update a Standard Profile

Updates a standard profile for a customer with new data.

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

Consider the following sample:

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

For information, see the user request object.

Response Object

Consider the following sample:

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

For information, see the user response object.

Statuses and Errors

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

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

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

Delete a Standard Profile

Deletes a standard profile for a customer from the system.

Endpoints

This method offers the following endpoints:

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

This action only applies to the User Profile service itself. It will mark the profile as deleted and make the user, or customer, profile ineligible for campaigns and audiences; it will NOT purge customer data from the entire system. For example, tables that hold a history of point modifications or other issuances will still contain records of operations made on behalf of the customer and will continue to include the internal SessionM user_id.

The endpoint is not designed to be used for bulk deletions of users over a short period of time. SessionM does not currently support a bulk delete or operations that purge customer data. This should be taken into account when planning creation and bulk loads of new customer profiles for testing or other non-production activities. For privacy-law related forget requests, please refer to the Data Privacy API.

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:

Request Object

Not applicable.

Response Object

Consider the following sample:

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

For information, see the user response object.

Statuses and Errors

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

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

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

Search for a Standard Profile

Searches for an existing standard customer profile based on attributes such as email address, external ID, and mobile phone number. Returns the specified customer profile with all of its associated attributes.

Endpoints

This method offers the following endpoints:

GET /priv/v1/apps/:api_key/users/search_users?email=test@example.com
GET /priv/v1/apps/:api_key/users/search_users?external_id=eutest17&user
GET /priv/v1/apps/:api_key/users/search_users?mobile_number=5089959991

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

Endpoint Parameters

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

Request Object

Not applicable.

Response Object

Consider the following sample:

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

For information, see the user response object.

Statuses and Errors

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

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

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

Custom Profile API

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

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

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

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

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.

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

Create a Custom Profile

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Response Object

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

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

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

Statuses and Errors

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

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

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

Create an Attribute in a Custom Profile

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

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

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Response Object

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

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

Statuses and Errors

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

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

Retrieve a Combined Standard and Custom Profile

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

user[user_profile]=true

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

Endpoints

This method offers the following endpoints:

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

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

Request Object

Not applicable

Response Object

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

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

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

Retrieve a Custom Profile

Retrieves a custom profile that contains only custom attributes.

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

Not applicable

Response Object

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

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

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

Statuses and Errors

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

Retrieve Product Recommendations Associated with a Custom Profile

Retrieves the product recommendations associated with a specified custom profile.

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

Not applicable

Response Object

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

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

Response Attributes for Products Object

Response Attributes for Set Object

Response Attributes for a Rank Object

Statuses and Errors

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

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

Update a Combined Standard and Custom Profile

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

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

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Response Object

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

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

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

Statuses and Errors

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

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

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

Update a Custom Profile

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Response Object

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

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

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

Statuses and Errors

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

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

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

Clear a Custom Profile Attribute

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

Request Object

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

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

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

Response Object

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

{  
   "status": "ok",
   "user": {  
      "user_profile": {  
         "_version": 84
      }
   }
}

Statuses and Errors

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

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

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

Patch an Attribute in a Custom Profile

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

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

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

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

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

Endpoints

This method offers the following endpoints:

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

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

Endpoint Parameters

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

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.

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

Request Object for Remove

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

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

This object contains the following attributes:

Request Attributes for Remove

Request Object for Add

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

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

This object contains the following attributes:

Request Attributes for Add

Request Object for Replace

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

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

This object contains the following attributes:

Request Attributes for Replace

Request Object for Move

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

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

This object contains the following attributes:

Request Attributes for Move

Request Object for Copy

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

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

This object contains the following attributes:

Request Attributes for Copy

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:

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

[{"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:

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

The response shown above corresponds to this request:

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

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

Response Object for Add

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

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

The response shown above corresponds to this request:

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

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

Response Object for Replace

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

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

The response shown above corresponds to this request:

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

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

Response Object for Move

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

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

The response shown above corresponds to this request:

[{"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:

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

The response shown above corresponds to this request:

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

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

Statuses and Errors

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

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

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