Using the Personalization API, developers can send the Treasure Data personalization service a customer identifier as well as updated customer information. A successful call to the personalization API performs the following actions:
Events configured in the POST body are ingested into Plazma. The Personalization API behaves similarly to the Ingest API. The additional behavior is that real-time tokens are validated and used to route to reactors (the back-end engines for real-time processing). Here is a diagram of the process flow for the API.
All matching personalization payloads are returned in the response payload. If the customer meets the entry criteria for a personalization, the system returns the text of offers as well as any additional customer information that may be pertinent to the offer.
- The API requires the real-time personalization service to be enabled on your account.
- The API supports a maximum of 50 tokens per personalization service.
- Ensure that tokens have been created in Data Workbench for authenticating the API call. (See Creating Real-time Personalization Services with Data Workbench.) the real-time event configurations are completed in Data Workbench.
- Ensure that at least one personalization has been configured in Audience Studio. (See Creating a Real-time Personalization with Audience Studio.)
The API must be authorized with
- a TD Write API key or Master API key for the account
- a personalization token
- the correct content type:
application/vnd.treasuredata.v1+json
For example, when making the API call from cURL, you would need both of these headers:
--header 'Authorization: TD1 {account_id}/{apikey}'
--header 'WP13n-Token: {account_id}/{instance_id}/{token}'
--header 'Content-Type: application/vnd.treasuredata.v1+json'The Web Personalization API has one ingestion endpoint per region:
{regionBaseURL}/{database}/{table}
Specify your endpoint using the baseURL for your region.
| Region | Base URL for Endpoint |
|---|---|
| USA (us01) | [us01.p13n.in.treasuredata.com] |
| Europe (eu01) | [eu01.p13n.in.treasuredata.com] |
| Japan (ap01 or "co.jp") | [ap01.p13n.in.treasuredata.com] |
The API uses the following path parameters:
- database — the database that was used to create and configure the personalization
- table — the table that contains the customer information.
For example, when making the API call from cURL, it could look like this:
POST https://{baseURL}/p13n_db/customer_info_table
The request body is a JSON object that contains at least one identifier for the customer. It can also contain information about the customer that needs to be updated in the real-time system. Here is an example of a request body:
{
"email": "user@example.com",
"customer_id": "4631",
"number_of_clicks": 10,
"age": "60",
"country": "INDIA",
"td_path": "0127100",
"td_path": "US43wtrewfrewrew"
}td_client_id: The client ID associated with the event.user_id: The user ID associated with the event.email: The email address associated with the event.event_name: The name of the event being ingested.attributes: A JSON object containing the attributes to be updated or used in the personalization.
The API returns a JSON response containing the following fields:
- Success — If the HTTP status code indicates success, offers are returned in the response payload
- Failure — If the HTTP status code indicates failure, an error code and message are returned in the response payload
200 Success
| Responses | Example | |
|---|---|---|
| 200 OK | with payload |  |
| without payload |  |
400 Failure
| Response | Example |
|---|---|
| 400 |  |
| 415 |  |
| 429 |  |
| Error Code | Message |
|---|---|
| 2003 | Kinesis error due to limit being exceeded (status 429) |
| 2013 | Lambda total concurrent execution exceeds the reserved concurrency (status 429) |
| 3000 | RT token was not provided (WP13n-Token header). |
| 3001 | RT token is not in configuration. |
| 3002 | RT token account conflicts with Authed user account. |
| 3003 | RT token is in an invalid format. |
| 3004 | Invalid event object. |
| 3005 | Request origin not in IP whitelist. |
curl --location '{baseURL}/webpages/personalization_results'
--header 'Content-Type: application/vnd.treasuredata.v1+json'
--header 'Authorization: TD1 {account_id}/{apikey}'
--header 'WP13n-Token: {account_id}/{instance_id}/{token}'
--data '{
"email": "high_user@test.com"
}'
{
"offers": {
"offer_for_high_loyalty": {
"attributes": {
"status": "high"
},
"batch_segments": [{
"id": "1588214"
}]
}
}
}