Personalization API Quickstart

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.

Limitations

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

Prerequisites

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

Authentication

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'

Endpoint

The Web Personalization API has one ingestion endpoint per region:

{regionBaseURL}/{database}/{table}

Specify your endpoint using the baseURL for your region.

Parameters

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

Request Body

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.

Responses

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

Example

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