User Profile Enrichment Service
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 is 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.
Creating Tokens
Hosts
Production
https://gateway.richrelevance.com/
QA
https://qa-gateway.richrelevance.com/
Staging
https://staging-gateway.richrelevance.com/
Note: You need to create different tokens for each environment. For example, token 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>/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. Each customer will have a unique client_id and client_secret.
POST-https://qa-gateway.richrelevance.com/attributes/v1/oauth2/token?grant_type=client_credentials&client_id=5934de97c95e1ced&client_secret=2l9dr0jkink11ad49hg93it52d
Sample Response
{
"token_type": "bearer"
"access_token": "M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd",
}
Example with cURL:
curl -X POST https://qa-gateway.richrelevance.com/attributes/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>/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/v1/<apiKey>/collections/rr-segments 'Authorization:Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd’
Example with cURL:
curl -H 'Authorization:Bearer <tokenValue>' https://qa-gateway.richrelevance.com/rr-segments/v1/<apiKey>/rr-segments
User Profile Enrichment API service Health check
To check the health of UPS Enrichment API service, you can use the following end point with the Bearer token that was obtained in the Creating Tokens step.
GET https://<host>/attributes/health 'Authorization:Bearer <tokenValue>'
Example with cURL:
curl -H 'Authorization:Bearer <tokenValue>' GET https://host/attributes/health
User Profile Enrichment Request
Below are actions and syntax for managing property definitions in a property definition collection.
User Profile Enrichment Request Syntax for User Attributes
Full URL: https://<host>/attributes/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}
|
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 request data should be send as an array. For PUT request data should be send as JSON Object. |
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"]
}
}
]
}
User Profile Enrichment Request Syntax for User Segments
Full URL: https://<host>/attributes/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}
|
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 request data should be send as an array. For PUT request data should be send 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 #3
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 #4
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"
}
}
]
}
User Profile Enrichment request syntax for User Linking
Full URL: https://<host>/attributes/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}
|
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 defined. For POST request data should be send as an array. For PUT request data should be send 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 #5
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 #6
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"
]
}
]
}
User Profile Enrichment request syntax for User Preferences
Customers can send user preferences via this end point and designate shopper preferences under the following specific verbs ‘like’, ‘dislike’, ‘neutral’ & ’Notforrecs’
Full URL: https://<host>/attributes/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}
|
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 #7
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 #8
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"
]
}
}
]
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
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
API Limits
|
HTTP |
Request Types |
Payload limit |
Throughput |
|
POST |
rr-segments/rr-userattributes/ userlinking/rr-userpreferences |
1000 user ID updates (records) per payload |
API will accept up to 1000 user ID updates per second. |
|
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