# 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.
![diagram](/assets/p13ncomponents.e8d975e76be52c9f076db5b21353fee0893dbe25471f80cb08dbd20b3dab979c.44ae19d7.png)
- 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](https://docs.treasuredata.com/smart/project-product-documentation/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](https://docs.treasuredata.com/smart/project-product-documentation/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.

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


# 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:


```json
{
    "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 | ![console URL](/assets/200_withpayload.6a17081057d1f481f54fe455d58363e7edf1ebdb28235c0a14dcd11e1794d97a.44ae19d7.png) |
|  | without payload | ![console URL](/assets/200_withoutpayload.1be94211277f00845dae26221c08270af2a21388a4d430933d8bcdb0b867d875.44ae19d7.png) |


**400 Failure**

| Response | Example |
|  --- | --- |
| 400 | ![return code](/assets/400_withcode.2fc741256a2c5b44e115bbfa8000c21d2fccb67efd3b3fe9fc0c5c820de75d7d.44ae19d7.png) |
| 415 | ![return code](/assets/415_withcode.72555e96e4b27ddd16794159ee6ea563b2257f762edc9527b77d3fb4f71ed515.44ae19d7.png) |
| 429 | ![console URL](/assets/429_withcode.33f467e072391ac8ce2296b3afdf2a3fc782df65c32d5116025cc9459d45f5db.44ae19d7.png) |


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


# Example


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