# 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](/products/my-settings/getting-your-api-keys)
- [Confirm your Postback API endpoint for your region](/apis/endpoints/endpoints) — 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.

```bash
# 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

```bash
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"}'
```

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

## Further Reading

- [Legacy Postback API Quickstart](/apis/postback/quickstart)
- [Treasure Toolbelt](https://toolbelt.treasuredata.com/) — Command Line Interface for Treasure AI services.
- [JavaScript SDK Quickstart](/products/customer-data-platform/integration-hub/streaming/td-javascript-sdk/quickstart)