Postback API v2 Quickstart

The Postback API v2 is the next-generation Postback ingestion endpoint. It exposes the same /postback/v3/event/{database}/{table} contract as the legacy Postback API, but is served from the new records.in.treasuredata.com host with header-based authentication only.

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.

What's different from the legacy Postback API

	Legacy Postback	Postback v2
Host	`in.treasuredata.com`	`<region>.records.in.treasuredata.com`
`X-TD-Write-Key` header	Supported	Supported
`Authorization: TD1 <key>` header	—	Supported
`?td_write_key=<key>` URL parameter	Supported	Not supported
Max request body	—	1,048,064 bytes
Path	`/postback/v3/event/{db}/{table}`	`/postback/v3/event/{db}/{table}`

The legacy URL-path API key (?td_write_key=...) is not accepted by v2. Move any client still using it to one of the two header forms below before cutting over.

Setup

Confirm your Write API key
Confirm your Postback API endpoint for your region — the v2 host is <region>.records.in.treasuredata.com.
TD database and table that you have write access to. This is where we will write data to using your API key.

Instructions

Sending a Request

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.

Parameter	Description
`database`	Specify destination database name in URL. Only alphabets/numbers or _ are allowed.
`table`	Specify destination table name in URL. Only alphabets/numbers or _ are allowed.

Authentication

v2 supports two header-based auth methods. Pick one — if both are sent, Authorization takes precedence.

# 1. Authorization header (TD1 scheme)
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789'

# 2. X-TD-Write-Key header
-H 'X-TD-Write-Key: 123/abcdef•••••••••••••••••••••••0123456789'

Sample Request

curl -i -X POST 'https://us01.records.in.treasuredata.com/postback/v3/event/db_test/table_1' \
-H 'Content-Type: application/json' \
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789' \
-d '{"email":"firstname.lastname@business.com","telephone":"555-555-5540"}'

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 May 2026 00:23:32 GMT
Strict-Transport-Security: max-age=31536000
Content-Length: 2
Connection: keep-alive

{}

Payload limits

Request body is capped at 1,048,064 bytes. Larger requests are rejected with 413 Payload Too Large.

API key validation

As with the legacy endpoint, requests with an invalid API key return 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.