{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Personalization API Quickstart","description":"Treasure Data Product Documentation · Collect and Unify · Segment and Activate · Experiment and Analyze · Decisioning Automate with AI Scale and Trust.","siteUrl":"https://docs.treasuredata.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"personalization-api-quickstart","__idx":0},"children":["Personalization API Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/p13ncomponents.9a1798d0d7a97dd6332d892b5af4636232fb9b9a72c7b794301f47cf6b8cd145.44ae19d7.avif","alt":"diagram","title":"#width=650px;"},"children":[]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limitations","__idx":1},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API requires the real-time personalization service to be enabled on your account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API supports a maximum of 50 tokens per personalization service."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure that tokens have been created in Data Workbench for authenticating the API call and that the real-time event configurations are completed in Data Workbench. (See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/customer-data-platform/data-workbench/parent-segments/creating-real-time-personalization-services-with-data-workbench"},"children":["Creating Real-time Personalization Services with Data Workbench"]},".)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure that at least one personalization has been configured in Audience Studio. (See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/customer-data-platform/real-time/creating-a-real-time-personalization-with-audience-studio"},"children":["Creating a Real-time Personalization with Audience Studio"]},".)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":3},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API must be authorized with"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a TD Write API key or Master API key for the account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a personalization token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the correct content type: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/vnd.treasuredata.v1+json"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, when making the API call from cURL, you would need these headers:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"--header 'Authorization: TD1 {account_id}/{apikey}'\n--header 'WP13n-Token: {account_id}/{instance_id}/{token}'\n--header 'Content-Type: application/vnd.treasuredata.v1+json'\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint","__idx":4},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Web Personalization API has one ingestion endpoint per region:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{regionBaseURL}/{database}/{table}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specify your endpoint using the baseURL for your region."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Region"},"children":["Region"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Base URL for Endpoint"},"children":["Base URL for Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["USA (us01)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://us01.p13n.in.treasuredata.com"},"children":["us01.p13n.in.treasuredata.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Europe (eu01)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://eu01.p13n.in.treasuredata.com"},"children":["eu01.p13n.in.treasuredata.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Japan (ap01 or \"co.jp\")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://ap01.p13n.in.treasuredata.com"},"children":["ap01.p13n.in.treasuredata.com"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parameters","__idx":5},"children":["Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses the following path parameters:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["database — the database that was used to create and configure the personalization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["table — the table that contains the customer information."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, when making the API call from cURL, it could look like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST https://us01.p13n.in.treasuredata.com/{database}/{table}"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-body","__idx":6},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request body is a JSON object that contains at least one identifier for the customer. It can also contain event data and additional attributes to be updated in the real-time system."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example","__idx":7},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"td_client_id\": \"42a508e2-d9b1-4baa-9eb2-6c3fb8bd5e16\",\n    \"td_url\": \"https://example.com/retail/shop/women\",\n    \"td_path\": \"/retail/shop/women\",\n    \"product_name\": \"women's-tank-top\",\n    \"product_category\": \"women\",\n    \"product_list\": [\"women's-running-shoes\", \"kids'-hoodie\", \"women's-tank-top\"],\n    \"category_list\": [\"women\", \"kids\"]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fields","__idx":8},"children":["Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td_client_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Treasure Data client ID associated with the customer (typically a UUID)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The full URL of the page where the event occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td_path"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The path portion of the URL (used for event filtering and personalization rules)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional attributes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["any"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any additional event data or customer attributes (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_category"]},", arrays like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_list"]},") to be ingested and used in personalization logic."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At least one identifier (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td_client_id"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},") must be provided to identify the customer. The personalization service evaluates the event data against your configured personalization rules and returns matching offers in the response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"responses","__idx":9},"children":["Responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API returns a JSON response containing the following fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Success : If the HTTP status code indicates success, offers are returned in the response payload"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Failure : If the HTTP status code indicates failure, an error code and message are returned in the response payload"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"200-success","__idx":10},"children":["200 Success"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Response"},"children":["Response"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["200 OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["with payload"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/200_withpayload.ba37d89aed62ffdb53aa23de5259c09bc4323d2a29321d2380a5a3308011386c.44ae19d7.avif","alt":"200 with payload"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["200 OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["without payload"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/200_withoutpayload.06c0f40417532c9f410f24fba0db5206c643ff049210b5434bc33be3ad16dfe0.44ae19d7.avif","alt":"200 without payload"},"children":[]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4xx-failure","__idx":11},"children":["4xx Failure"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Response"},"children":["Response"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/400_withcode.b2c2bda7d39f0ec159c36f85baa84d20b1deb8cafc9e9cfa817f1b5293840be2.44ae19d7.avif","alt":"400 error"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["415"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/415_withcode.4f74d8130028d1ea9123acca050feaf662a4a11ae84df584cea07bcfee97a94e.44ae19d7.avif","alt":"415 error"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/429_withcode.16356b8c9d4e5f753e82428c07c5e1c117699d693a133ac4e31d819e1c247d49.44ae19d7.avif","alt":"429 error"},"children":[]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-codes","__idx":12},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Message"},"children":["Message"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2003"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kinesis error due to limit being exceeded (status 429)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2013"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lambda total concurrent execution exceeds the reserved concurrency (status 429)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3000"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RT token was not provided (WP13n-Token header)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3001"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RT token is not in configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3002"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RT token account conflicts with Authed user account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3003"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RT token is in an invalid format."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3004"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid event object."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3005"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request origin not in IP whitelist."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-1","__idx":13},"children":["Example"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request","__idx":14},"children":["Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export BASE_URL=\"us01.p13n.in.treasuredata.com\"\nexport DATABASE=\"your_database\"\nexport TABLE=\"pageviews\"\nexport API_KEY=\"1234/abcdefghijklmnopqrstuvwxyz\"\nexport ACCOUNT_ID=\"12345\"\nexport INSTANCE_ID=\"67890\"\nexport TOKEN=\"abcdef123456\"\n\ncurl -X POST \"https://${BASE_URL}/${DATABASE}/${TABLE}\" \\\n--header 'Content-Type: application/vnd.treasuredata.v1+json' \\\n--header \"Authorization: TD1 ${API_KEY}\" \\\n--header \"WP13n-Token: ${ACCOUNT_ID}/${INSTANCE_ID}/${TOKEN}\" \\\n--data '{\n    \"td_client_id\": \"42a508e2-d9b1-4baa-9eb2-6c3fb8bd5e16\",\n    \"td_url\": \"https://example.com/retail\",\n    \"td_path\": \"/retail\"\n}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":15},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"offers\": {\n    \"offer_for_high_loyalty\": {\n      \"attributes\": {\n        \"status\": \"high\"\n      },\n      \"batch_segments\": [{\n          \"id\": \"1588214\"\n      }]\n    }\n  }\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Personalization API Quickstart","id":"personalization-api-quickstart","depth":1},{"value":"Limitations","id":"limitations","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"Endpoint","id":"endpoint","depth":2},{"value":"Parameters","id":"parameters","depth":2},{"value":"Request Body","id":"request-body","depth":2},{"value":"Example","id":"example","depth":3},{"value":"Fields","id":"fields","depth":3},{"value":"Responses","id":"responses","depth":2},{"value":"200 Success","id":"200-success","depth":3},{"value":"4xx Failure","id":"4xx-failure","depth":3},{"value":"Error Codes","id":"error-codes","depth":3},{"value":"Example","id":"example-1","depth":2},{"value":"Request","id":"request","depth":3},{"value":"Response","id":"response","depth":3}],"frontmatter":{"seo":{"title":"Personalization API Quickstart"}},"lastModified":"2026-02-24T03:19:14.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/p13n-api","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}