Profile Command API

Introduction

The Profile Command API allows an organization to Opt Out on behalf of its users.

Removes the historical profile data from the user profile service.
Future profile data will not be added to the user profile service.
The client should continue to pass the same userid for the user. If they create a new userid then we will treat them as a new user.
Once opted out, the user cannot be opted back in and the user's profile will be removed from the Personalization cloud.

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 Profile Command API 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 Profile Command API service is set at 8 hours, equivalent to 28,800 seconds. To ensure uninterrupted service utilization without encountering authorization failures, requesting a new bearer token every 8 hours is recommended.

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, 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>/profile-command/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 profile command API 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/profile-command/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 must be requested to continue accessing the API.

Example with cURL:

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

Error Response:

{
"error_description": "Invalid client authentication",
"error": "invalid_client"
}

or

{
"error_description": "Invalid grant_type",
"error": "unsupported_grant_type"
}

Requests to Algonomy Gateway Require the Bearer Token

For every Profile Command API call, the bearer token value obtained in the Creating Tokens step should be included as part of the Authorization header.

https://<host>/profile-command/v1/<apiKey>/optOut/<userId>    
'Authorization:Bearer <tokenValue>'

Example: To optOut from personalization and delete the profile associated with a specific user ID, use the below API request.

PUT https://qa-gateway.richrelevance.com/profile-command/v1/<apiKey>/optOut/<userId>
'Authorization:Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd’

Example with cURL:

curl -H 'Authorization:Bearer <tokenValue>' https://qa-gateway.richrelevance.com/profile-command/v1/<apiKey>/optOut/userId

Updating Opt Out

PUT https://<host>/profile-command/v1/<apiKey>/optOut/<userId>

PUT: Enable the opt-out of a user with the given ID.

Name	Required or Optional	Description
userId	Required (string)	A path parameter that specifies the user ID on whose behalf the data is being sent.

Profile Command - API Body

Element	Data Type	Required or Optional	Description	Values
type	String	Required	"optOut" is the only value currently available. In the future other types of data will be able to be sent.	optOut
enableOptOut	String	Required	Boolean value: true or false. "true" will opt the user out.	true

Example

Request:

Substitute the userId in its placeholder and the access_token received from the OAuth request in the "token" placeholder.

curl -X PUT \
  https://gateway.richrelevance.com/profile-command/v1/<apikey>/optOut/{userId} \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
"type": "optOut",
"enableOptOut": true
}'

Good Response:

{}

Error Response:

{
"error_description": "The access token is invalid or has expired",
"error": "invalid_token"
}

Throttling of API requests

Profile-Command API requests are subject to rate limiting as described below.

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

API Limits

HTTP Method	Request Types	Payload limit	Throughput
PUT	profile-command/v1/apikey/optOut/userId	N.A	API will accept up to 100 user ID updates per second.