Developers · Postal API
Postal API, specification v1
HTTPS and JSON. Field names in snake_case, dates as YYYY-MM-DD, money as a decimal string. We validate each item in the same request, so the response is the result.
Specification v1PlannedThe endpoints are planned. We open a sandbox for each client before production.
Basics
| Item | Value |
|---|---|
| Production | https://api.alliedchb.com/v1 |
| Sandbox | https://api-test.alliedchb.com/v1 |
| Authentication | Headers X-Client-Id and X-Client-Secret, one pair for each environment. We send the secret by a secure channel. |
| Tracing | Optional header X-Request-Id. |
| Idempotency | By item_id: a second POST of the same S10 number returns DUPLICATE. |
| Batch size | 1 to 5,000 items in each request. |
| Schema | postal-items.v1.json (JSON Schema 2020-12). |
Endpoints
- POST/v1/itemsSend a batch of items. Each item gets its own result.
- GET/v1/items/{item_id}The status history of one item: the entry number, the CBP and FDA events and the duty.
- GET/v1/healthService check. No authentication.
Send a batch
The same request in three languages. The body is a
postal-items.v1 batch.curl -X POST https://api-test.alliedchb.com/v1/items \ -H "X-Client-Id: $ALLIED_CLIENT_ID" \ -H "X-Client-Secret: $ALLIED_CLIENT_SECRET" \ -H "Content-Type: application/json" \ --data @postal-items.v1.example.jsonResponse: one result for each item
200 OK · application/json
{ "batch_ref": "POST-DISPATCH-2026-10-01-A", "results": [ { "item_id": "CP123456785CA", "result": "ACCEPTED", "route": "ET13", "ace_bill": { "mode": "AIR", "bill_type": "R", "issuer": "", "number": "SFPCP123456785CA" }, "warnings": [], "field_errors": [] } ]}Errors
A request that fails as a whole gets this envelope. A problem with one item comes back in the result of that item.
| HTTP | Error | When |
|---|---|---|
| 400 | INVALID_JSON | The body is not valid JSON. |
| 401 | UNAUTHORIZED | The client ID or the secret is missing or incorrect. |
| 422 | VALIDATION_ERROR | The batch does not match the schema. field_errors gives each problem. |
| 429 | RATE_LIMITED | Too many requests. Wait, then send again. |
| 500 | SERVER_ERROR | Our error. Send the same batch again: a repeated item returns DUPLICATE. |
422 · VALIDATION_ERROR
{ "error": "VALIDATION_ERROR", "message": "The batch does not match postal-items.v1.json", "field_errors": [ { "field": "items[3].contents[0].hs_code", "code": "SCHEMA", "message": "required" } ]}Validation codes
We check each item against these rules.
| Code | Rule | Result |
|---|---|---|
| SCHEMA | The item matches postal-items.v1.json. | Reject |
| S10_FORMAT | 2 letters, 8 digits, 1 check digit and a 2-letter country code. | Reject |
| S10_CHECK_DIGIT | Weights 8 6 4 2 3 5 9 7. A result of 10 becomes 0, and 11 becomes 5. | Reject |
| ZIP_UNKNOWN | The addressee ZIP code is a valid U.S. ZIP code. | Reject |
| S10_US_ISSUED | The number ends in US, so USPS issued it. Entry type 13 needs the number from the foreign post. | Warning |
| OVER_2500 | The item value is over $2,500 at the CBP exchange rate. | Formal entry |
| DUPLICATE | We already have this S10 number. | Duplicate |
Status list
The status of an item in
GET /v1/items/{item_id}.| Status | Meaning |
|---|---|
| RECEIVED | We have the item data. |
| VALIDATED | The item passed the checks. |
| FILED | We sent the entry to CBP. The entry number is in the response. |
| CBP_RELEASED | CBP released the item. |
| CBP_HOLD | CBP holds the item. |
| FDA_HOLD | FDA holds the item for review. |
| FDA_MAY_PROCEED | FDA released the item. |
| REJECTED | The item failed a check. The response gives each problem. |
Start with a data test
Send us a sample dispatch in JSON, CSV or Excel. We report each gap in the data before the first entry. Quote on request.
Call (908) 291-8001 or email mail@alliedchb.com