User Profile Enrichment Service

Last updated
Save as PDF

Introduction

The User Profile Enrichment Service enables marketers to update single or multiple user profiles simultaneously with User Attributes, User Segments, and User Linking information. It provides a way to store user attribute information in near-real time. Once successful, this data becomes available for use with all Algonomy products.

When an API request is processed, any existing data for a user in the Algonomy Omnichannel Personalization Cloud is replaced with the data from the payload.

Note: Any users who are not mentioned in the update will be left untouched.

Supported Enrichment Types

User Profile Enrichment Service allows you to perform the following 3 types of enrichments to user profiles:

Segments: To define a list of segments to be associated with each user specified in the payload.
User Attributes: To define a list of user attributes associated with each user.
User Linking: To define a list of user profiles to which a master user profile can be linked with.
Omnichannel Personalization Cloud supports two types of user linking, such as explicit user linking and grouped user linking.
User Preferences: To synchronize a set of shopper preferences against a user profile using a specific list of verbs ‘like’, ‘dislike’, ‘neutral’ & ’Notforrecs’.

Authentication to Algonomy Gateway

The authentication to the Algonomy API gateway is facilitated using Oath2.0- grant-type client credentials.

Note: Contact your Algonomy Customer Support Team to request a client_id and client_secret for your exclusive use.

Algonomy will create client_id and client_secret for each site (configured for each customer) and will share them in the requested method.

The client_id and client_secret key are required to obtain bearer tokens for accessing the UPS Enrichment service. Bearer tokens have a system-defined time-to-live (TTL) validity period. Once TTL is reached, customer systems need to request a new bearer token with the provided client_id & client_secret.

Note: The bearer token Time to Live (TTL) for the UPS Enrichment API service is set at 8 hours, equivalent to 28,800 seconds. To ensure uninterrupted utilization of the service without encountering authorization failures, it is recommended to request a new bearer token every 8 hours.

Creating Tokens

Hosts

Production

https://gateway.richrelevance.com/

https://qa-gateway.richrelevance.com/

Staging

https://staging-gateway.richrelevance.com/

Note: You need to create different tokens for each environment. For example, tokens created for the QA environment can be used only in the QA environment. You cannot use it in the production environment.

To create tokens, use the request syntax below:

POST https://<host>/<attributes>/api/v1/oauth2/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant.

Sample Request

To obtain a token for the UPS Enrichment service in the QA environment.

In this example, the client_id is5934de97c95e1ced and the client_secret is 2l9dr0jkink11ad49hg93it52d.Eachcustomer will have a unique client_id and client_secret.

POST-https://qa-gateway.richrelevance.com/attributes/api/v1/oauth2/token?grant_type=client_credentials&client_id=5934de97c95e1ced&client_secret=2l9dr0jkink11ad49hg93it52d

Sample Response

    
{  
"token_type": "bearer"  
"access_token": "M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd",
"expires_in": 28800      
}

Note: The "expires_in" value returned in the OAuth token response indicates the duration of the bearer token's validity in seconds. This directly corresponds to the token's Time to Live (TTL). For example, if "expires_in" is set to 28,800 seconds, the token remains valid for exactly 28,800 seconds, which is 8 hours. After 8 hours, the token will expire, and a new token will need to be requested to continue accessing the API.

Example with cURL:

curl -X POST https://qa-gateway.richrelevance.com/attributes/api/v1/oauth2/token -d "grant_type=client_credentials" -d "client_id=5934de97c95e1ced" -d "client_secret=2l9dr0jkink11ad49hg93it52d"

Requests to Algonomy Gateway Require the Bearer Token

For every UPS Enrichment API call, the bearer token value that was obtained in the Creating Tokens step should be included as part of the Authorization header.

https://<host>/<attributes>/api/v1/<apiKey>      
'Authorization:Bearer <tokenValue>'

Example: To update segments associated with a specific user ID, use the below API request.

PUT https://qa-gateway.richrelevance.com/attributes/api/v1/<apiKey>/collections/rr-segments
'Authorization:Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd’

Example with cURL:

curl -H 'Authorization:Bearer <tokenValue>' https://qa-gateway.richrelevance.com/rr-segments/api/v1/<apiKey>/rr-segments

User Profile Enrichment Request Syntax for User Attributes

Full URL: https://<host>/attributes/api/v1/<apiKey>/rr-userattributes

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	Unique identifier for a customer's environment. For example, if a customer has multiple environments in production or staging, each instance will have a unique apiKey.

Action and Syntax

Action	Syntax
Update User Attributes for a single user.	PUT {baseURL}/attributes/api/v1/{apikey}/{rr-userattributes}
Update User Attributes for multiple users.	POST {baseURL}/attributes/api/v1/{apikey}/{rr-userattributes}

Action

Syntax

Update User Attributes for a single user.

PUT {baseURL}/attributes/api/v1/{apikey}/{rr-userattributes}

Update User Attributes for multiple users.

POST {baseURL}/attributes/api/v1/{apikey}/{rr-userattributes}

UPS Enrichment - User Attribute (API Body)

Element	Description	Data Type	Optional/ Mandatory	Values
<siteId>	siteId associated with the customer Note: This field is not required for Personalization customers.	Integer	Optional	1723
Data	Under data userId and the associations with attributes, segments, and user linking should be defined. For POST requests data should be sent as an array. For PUT requests data should be sent as JSON Object. Note: If you send an empty payload with a userId, it will trigger the deletion of the current segment, user attribute, and user linking associations	Array/JSON Object		data": { { "userId": "18980065", "value": {"fav_color": ["red", "green"] } } }
userId	UserId associated with a unique user inside personalization	string	Mandatory	18980065

Example #1

Updating user attributes for a single user.

Apikey:- 12345

userId: 123abcde

HTTP Method: PUT

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-userattributes

Payload:

{
    "data": {
        "userId": "123abcde",
        "value": {
“fav_color": ["red", "green"]
}            
        }
    }

Example #2

Updating user attributes for multiple users.

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-userattributes

Payload:

{
"data": [
{
"userId": "123abcde",
"value": {"fav_color": ["red", "green"]
}
},
{
"userId": "345erty",
"value": {"fav_color": ["blue", "green"]
}
}
]
}

Example #3

Deleting user attributes for multiple users.

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-userattributes

Payload:

{
"data": [
{
"userId": "123abcde",
"value": {
}
},
{
"userId": "345erty",
"value": {
}
}
]
}

User Profile Enrichment Request Syntax for User Segments

Full URL: https://<host>/attributes/api/v1/<apiKey>/rr-segments

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	Unique identifier for a customer's environment. For example, if a customer has multiple environments in production or staging, each instance will have a unique apiKey.

Action and Syntax

Action	Syntax
Update user segments for a single user	PUT {baseURL}/attributes/api/v1/{apikey}/{rr-segments}
Update user segments for multiple users	POST {baseURL}/attributes/api/v1/{apikey}/{rr-segments}

Action

Syntax

Update user segments for a single user

PUT {baseURL}/attributes/api/v1/{apikey}/{rr-segments}

Update user segments for multiple users

POST {baseURL}/attributes/api/v1/{apikey}/{rr-segments}

UPS Enrichment - User Segments (API Body)

Element	Description	Data Type	Optional/ Mandatory	Values
<siteId>	siteId associated with the customer Note: This field is not required for Personalization customers.	integer	Optional	1723
Data	Under data userId and the associations with segments should be defined. For POST requests data should be sent as an array. For PUT requests data should be sent as JSON Object.	Array/JSON Object		data": { { "userId": "9fab6bce8de6f36cd62f96f87b1a524d862ec0c09e1f3ade8285b1461babf09a", "value": { "Member": "isMember-t", "Non-CardHolder": "isMCHolder-f" } }
userId	UserId associated with a unique user inside personalization	string	Mandatory	9fab6bce8de6f36cd62f96f87b1a524d862ec0c09e1f3ade8285b1461babf09a

Example #4

Updating user segments for a single user.

Apikey:- 12345

userId: 123abcde

HTTP Method: PUT

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-segments

Payload:

{
    "data": {
        "userId": "123abcde",
        "value": {
            "Member": "isMember-t1",
            "Non-CardHolder": "isMCHolder-f3"
        }
    }
}

Example #5

Updating user segments for multiple users.

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-segments

Payload:

{
  "data": [
    {
      "userId": "123abcde",
      "value": {
        "Non-CardHolder": "isMCHolder-m",
        "Non-Mem": "isMember-f"
      }
    },
    {
      "userId": "345erty",
      "value": {
        "Non-CardHolder": "isMCHolder-k",
        "Non-Mem": "isMember-k"
      }
    }
  ]
}

Example #6

Deleting user segments for multiple users.

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-segments

Payload:

{
  "data": [
    {
      "userId": "123abcde",
      "value": {
      }
    },
    {
      "userId": "345erty",
      "value": {
      }
    }
  ]
}

User Profile Enrichment request syntax for User Linking

Full URL: https://<host>/attributes/api/v1/<apiKey>/userlinking

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	Unique identifier for a customer's environment. For example, if a customer has multiple environments in production or staging, each instance will have a unique apiKey.

Action and Syntax

Action	Syntax
Update user linking for a single user	PUT {baseURL}/attributes/api/v1/{apikey}/{userlinking}
Update user linking for multiple users	POST {baseURL}/attributes/api/v1/{apikey}/{userlinking}

Action

Syntax

Update user linking for a single user

PUT {baseURL}/attributes/api/v1/{apikey}/{userlinking}

Update user linking for multiple users

POST {baseURL}/attributes/api/v1/{apikey}/{userlinking}

UPS Enrichment - User Linking (API Body)

Element	Description	Data Type	Optional/ Mandatory	Values
<siteId>	siteId associated with the customer Note: This field is not required for Personalization customers.	integer	Optional	1723
Type	To indicate if the expected user linking is grouped. By default, the system will apply explicit user linking , that is, if the type is not set In the payload.	String	Optional	grouped
Data	Under data userId associations with user linking should be defined. For POST requests data should be sent as an array. For PUT requests data should be sent as JSON Object.	Array/JSON Object		"data": { "userId": "18980069", "value": [ "1234", "9fab6bce8de6f36cd62f96f87b1a524d862ec0c09e1f3ade8285b1461babf09b" ] }
userId	UserId associated with a unique user inside personalization	string	Mandatory	18980069

Example #7

Updating user linking for a single user with explicit user mapping.

Apikey:- 12345

userId: 123abcde

HTTP Method: PUT

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/userlinking

Payload:

"data": {
        "userId": "123abcde",
        "value": [
            "1234",
            "9fab6bce8de6f36cd62f96f87b1a524d862ec0c09e1f3ade8285b1461babf09b"
        ]
    }

Example #8

Updating user linking for multiple users with grouped user mapping.

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/userlinking

Payload:

{
    "type":"grouped",
    "data": [
        {
            "userId": "123abcde",
            "value": [
                "983448b36267fc69"
            ]
        },
        {
            "userId": "345erty",
            "value": [
                "983448b36267fc69"
            ]
        }
    ]
}

Example #9

Deleting the existing user mapping associated with for a single userId.

Apikey:- 12345

userId: 123abcde

HTTP Method: PUT

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/userlinking

Payload:

"data": {
        "userId": "123abcde",
        "value": [
        ]
    }

User Profile Enrichment request syntax for User Preferences

Customers can send user preferences via this endpoint and designate shopper preferences under the following specific verbs ‘like’, ‘dislike’, ‘neutral’ & ’Notforrecs’

Full URL: https://<host>/attributes/api/v1/<apiKey>/rr-userpreferences

'Authorization:Bearer <tokenValue>’

Parameters

Parameter	Mandatory/Optional	Description
apiKey	Mandatory	Unique identifier for a customer's environment. For example, if a customer has multiple environments in production or staging, each will have a unique apiKey.

Action and Syntax

Action	Syntax
Update user preferences for a single user	PUT {baseURL}/attributes/api/v1/{apikey}/{rr-preferenes}
Update user preferences for multiple users	POST {baseURL}/attributes/api/v1/{apikey}/{rr-preferences}

Action

Syntax

Update user preferences for a single user

PUT {baseURL}/attributes/api/v1/{apikey}/{rr-preferenes}

Update user preferences for multiple users

POST {baseURL}/attributes/api/v1/{apikey}/{rr-preferences}

UPS Enrichment - User Preferences (API Body)

Element	Description	Data Type	Optional/ Mandatory	Values
<siteId>	siteId associated with the customer Note: This field is not required for Personalization customers.	integer	Optional	1723
Data	Under data user preferences as ‘like’, ‘dislike’, and ‘neutral’ verbs are to be provided against product IDs For POST requests data is to be sent as an array while for PUT requests it needs to be sent as JSON Object	Array/JSON Object		"data": [ { "userId": "18980065", "value": { "like": [ "prod102710181y", "prod102480201x" ], "disLike": [ "prod10150001", "prod101520076" ] } } ]
userId	UserId associated with a unique user inside personalization	string	Mandatory	18980065

Example #10

Updating user preferences (like, dislike) for multiple users

Apikey:- 12345

userId: 123abcde

HTTP Method: PUT

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/rr-userpreferences

Payload:

"data": {
        "userId": "123abcde",
            "value": {
                "like": [
                    "prod102710181y",
                    "prod102480201x"
                ],
                "disLike": [
                    "prod10150001",
                    "prod101520076"
                ]
            }
    }

Example #11

Updating user preferences (like, dislike) for multiple users

Apikey:- 12345

userId: 123abcde, 345erty

HTTP Method: POST

URL: https://gateway.richrelevance.com/attributes/api/v1/12345/userlinking

Payload:

"data": [
        {
            "userId": "123abcde",
            "value": {
                "like": [
                    "prod102710181y",
                    "prod102480201x"
                ],
                "disLike": [
                    "prod10150001",
                    "prod101520076"
                ]
            }
        },
        {
            "userId": "345erty",
            "value": {
                "like": [
                    "prod102710181y",
                    "prod102480201x"
                ],
                "disLike": [
                    "prod10150001",
                    "prod101520076"
                ]
        }
     }
    ]

UPS Enrichment Status

The Personalization platform provides an API endpoint to check the status details of each UPS enrichment ingestion process. After each ingestion, the system generates an automated response as shown in the example below, which includes a jobId. You can verify the status of each ingestion process by querying the status service with that jobId.

{
    "version": 1685779637992,
    "jobId": "a86d0680-01e5-11ee-8080-808080808080",
    "message": "Accepted"
}

The status service API requires a different bearer token compared to the one used during the import process. For more information, refer to the Creating Tokens section.

To create a bearer token that can be used with the status service, use the request syntax given below:

POST https://<host>/common-status/v1/oauth2/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant. You can use the same client_id and client_secret you used to generate the bearer token for the UPS Enrichment API service.

For each Status API call, include the bearer token value obtained in the previous step as part of the Authorization header.

https://<host>/common-status/v1/<apiKey>/job/<jobId>/events      
'Authorization:Bearer <tokenValue>'

Example: To get the detailed status information for an import job using a jobId, use the following format

GET https://qa-gateway.richrelevance.com/common-status/v1/<apiKey>/job/f29dd805-0156-11ee-ad68-7d780afc9f2c/events?showAll=True

Parameters

Parameter	Mandatory/Optional	Description
showAll	Optional	True/False.

Pagination Parameters

Pagination is conditional and is invoked only when the number of "rows" returned by the status service exceeds a specified number or when the "showAll" parameter is included in the API call. By default, the service returns 5000 rows on a single page.

If the “rows” parameter is included, the list of status messages will be paginated and a pagination JSON is included at the beginning of the response. The pagination response will contains the number of status messages returned as well as the next page token.

Status Examples

Failed Status: An example of a status service response, when a UPS Enrichment API fails to update the ingested attributes.

{
    "summary": {
        "owner": {
            "ownerType": "SITE",
            "id": 608
        },
        "job-id": "a86d0680-01e5-11ee-8080-808080808080",
        "job-status": "FAILED",
        "job-batches": 1,
        "job-tasks": 2,
        "total-events": 2,
        "query-param": "showAll=true&rows=5000",
        "ERROR": 1,
        "SUMMARY": 1,
        "job": {
            "owner": {
                "ownerType": "SITE",
                "id": 608
            },
            "jobId": "a86d0680-01e5-11ee-8080-808080808080",
            "appId": {
                "appType": "UPS",
                "id": 1077
            },
            "batches": 1,
            "tasks": 2,
            "name": "Attribute API process for version 1685779637992",
            "childJobs": 0,
            "rootSource": "attributes-api-process/qa1",
            "apps": [
                "attributes-api-process"
            ],
            "datacenters": [
                "qa1",
                "qa2"
            ],
            "attributes": {
                "eventSource": "attributes-api-server",
                "eventDest": "batch-writer",
                "loadType": "api",
                "apiKey": "608",
                "version": "1685779637992",
                "httpStatus": "200",
                "type": "rr-userattributes"
            },
            "restarts": 0,
            "status": "FAILED",
            "jobCreated": "2023-06-03T08:07:17.992Z",
            "lastModified": "2023-06-03T08:07:27.402Z",
            "duration": "00:00:09"
        }
    },
    "result": [
        {
            "taskId": "ae08ba69-01e5-11ee-9153-57ccb6048b0a",
            "statusId": "ae08e17a-01e5-11ee-9153-7971a339aaea",
            "batch": 1,
            "type": "Application",
            "message": "Failed to update data to cassandra: com.rr.ups.attribute.api.common.exception.AttributeApiProcessException: java.lang.RuntimeException: AttributesApiWriter aborting due to error",
            "level": "ERROR",
            "attributes": {
                "eventSource": "batch-writer",
                "eventDest": "cassandra",
                "loadType": "api",
                "apiKey": "608",
                "version": "1685779637992",
                "message": "Failed to update data to cassandra: com.rr.ups.attribute.api.common.exception.AttributeApiProcessException: java.lang.RuntimeException: AttributesApiWriter aborting due to error",
                "type": "rr-userattributes"
            },
            "source": "attributes-api-process",
            "datacenter": "qa2",
            "timestamp": "2023-06-03T08:07:27.402021800Z"
        },
        {
            "taskId": "a86da2c5-01e5-11ee-931f-45ec911bc2e4",
            "statusId": "a86dc9d6-01e5-11ee-931f-a554e9e3519f",
            "batch": 1,
            "type": "Application",
            "message": "Validated and accepted 1 records for processing",
            "level": "SUMMARY",
            "attributes": {
                "eventSource": "attributes-api-server",
                "eventDest": "batch-writer",
                "loadType": "api",
                "apiKey": "608",
                "version": "1685779637992",
                "httpStatus": "200",
                "type": "rr-userattributes"
            },
            "source": "attributes-api-process",
            "datacenter": "qa1",
            "timestamp": "2023-06-03T08:07:17.997000600Z"
        }
    ]
}

Throttling of API requests

UPS Enrichment API requests are subject to rate limiting as described below.

If the system receives requests above the specified throughput, the API will respond with HTTP 429 Too Many Requests.

Compressing the Payload and Payload Size

Each payload should be compressed using gzip. Add the encoding header to the Attribute API request — Content-Encoding: gzip. This needs to be matched with the compression format you are using — gzip. The maximum payload size that the API can support is 50 KB. If the system receives requests with a payload larger than 50 KB, then the API will respond with HTTP 413 Request Entity too Large.

API Limits

HTTP Method	Request Types	Payload limit	Throughput
POST	rr-segments/rr-userattributes/ userlinking/rr-userpreferences	1000 user ID updates (records) per payload OR 50 KB (whichever is lower)	API will accept up to 1000 user ID updates per second. This can be batched according to convenience i.e., if batched in such a way that its 100 user profile updates are consolidated in a request, API will accept 10 such requests per second before throttling. Max payload size allowed is 50 KB.
PUT	rr-segments/rr-userattributes/ userlinking/rr-userpreferences	1 user ID update per payload	Max 1000 requests per second.

Tags recommended by the template: article:topic