{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Postback API v2 Quickstart","description":"Learn how to use the Treasure AI Postback API v2 to send event data using header-based authentication on the records.in.treasuredata.com endpoint.","siteUrl":"https://docs.treasure.ai","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":"postback-api-v2-quickstart","__idx":0},"children":["Postback API v2 Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Postback API v2 is the next-generation Postback ingestion endpoint. It exposes the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/postback/v3/event/{database}/{table}"]}," contract as the legacy Postback API, but is served from the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["records.in.treasuredata.com"]}," host with header-based authentication only."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Postback API v2 for the same use cases as the legacy Postback API — custom webhooks, environments where the JS SDK or TD Logger cannot run, or single-record imports triggered by an external application."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-different-from-the-legacy-postback-api","__idx":1},"children":["What's different from the legacy Postback API"]},{"$$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":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Legacy Postback"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Postback v2"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Host"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in.treasuredata.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<region>.records.in.treasuredata.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-TD-Write-Key"]}," header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supported"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supported"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: TD1 <key>"]}," header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supported"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?td_write_key=<key>"]}," URL parameter"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supported"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Not supported"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Max request body"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1,048,064 bytes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/postback/v3/event/{db}/{table}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/postback/v3/event/{db}/{table}"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The legacy URL-path API key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?td_write_key=..."]},") is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," accepted by v2. Move any client still using it to one of the two header forms below before cutting over."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup","__idx":2},"children":["Setup"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/my-settings/getting-your-api-keys"},"children":["Confirm your Write API key"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/endpoints/endpoints"},"children":["Confirm your Postback API endpoint for your region"]}," — the v2 host is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<region>.records.in.treasuredata.com"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TD database and table that you have write access to. This is where we will write data to using your API key."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"instructions","__idx":3},"children":["Instructions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sending-a-request","__idx":4},"children":["Sending a Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add your TD Write API key as a header, put the database and table in the URL, and include your data in the post request body. Send your data as a JSON payload."]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Parameter"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"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":["database"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify destination database name in URL. Only alphabets/numbers or _ are allowed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["table"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify destination table name in URL. Only alphabets/numbers or _ are allowed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication","__idx":5},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["v2 supports two header-based auth methods. Pick one — if both are sent, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," takes precedence."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# 1. Authorization header (TD1 scheme)\n-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789'\n\n# 2. X-TD-Write-Key header\n-H 'X-TD-Write-Key: 123/abcdef•••••••••••••••••••••••0123456789'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sample-request","__idx":6},"children":["Sample Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -i -X POST 'https://us01.records.in.treasuredata.com/postback/v3/event/db_test/table_1' \\\n-H 'Content-Type: application/json' \\\n-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789' \\\n-d '{\"email\":\"firstname.lastname@business.com\",\"telephone\":\"555-555-5540\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"HTTP/1.1 200 OK\nContent-Type: application/json\nDate: Thu, 15 May 2026 00:23:32 GMT\nStrict-Transport-Security: max-age=31536000\nContent-Length: 2\nConnection: keep-alive\n\n{}\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payload-limits","__idx":7},"children":["Payload limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Request body is capped at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1,048,064 bytes"]},". Larger requests are rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["413 Payload Too Large"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-key-validation","__idx":8},"children":["API key validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As with the legacy endpoint, requests with an invalid API key return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," synchronously; key validation runs asynchronously after the response is sent. An invalid key surfaces as an authentication failure in the ingestion pipeline rather than at the HTTP layer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":9},"children":["Further Reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/postback/quickstart"},"children":["Legacy Postback API Quickstart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://toolbelt.treasuredata.com/"},"children":["Treasure Toolbelt"]}," — Command Line Interface for Treasure AI services."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/customer-data-platform/integration-hub/streaming/td-javascript-sdk/quickstart"},"children":["JavaScript SDK Quickstart"]}]}]}]},"headings":[{"value":"Postback API v2 Quickstart","id":"postback-api-v2-quickstart","depth":1},{"value":"What's different from the legacy Postback API","id":"whats-different-from-the-legacy-postback-api","depth":2},{"value":"Setup","id":"setup","depth":2},{"value":"Instructions","id":"instructions","depth":2},{"value":"Sending a Request","id":"sending-a-request","depth":3},{"value":"Authentication","id":"authentication","depth":3},{"value":"Sample Request","id":"sample-request","depth":4},{"value":"Payload limits","id":"payload-limits","depth":3},{"value":"API key validation","id":"api-key-validation","depth":3},{"value":"Further Reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Postback API v2 Quickstart","description":"Learn how to use the Treasure AI Postback API v2 to send event data using header-based authentication on the records.in.treasuredata.com endpoint."}},"lastModified":"2026-06-28T02:58:35.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/postback-v2/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}