PostZen
Contacts

Bulk create contacts

POST
/v1/contacts/bulk

Requires read_write. Limited to 20 imports/hour/user. Runs as one mutation. Processes 1–1000 rows with individual errors; duplicate channel or profile email skips the row and merges only tags. Remaining rows fail once the contact cap is reached. platform is ignored with accountId and rejected without it. Envelope profile/account errors fail the request.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Import 1–1000 contacts into one profile. A supplied accountId applies to every row. Duplicates by channel (first) or profile email are skipped and only new tags are merged, retaining existing case. A merged tag list over 50 is a row error. When the 5000-contact cap is reached, remaining rows receive contact limit reached errors.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/contacts/bulk" \  -H "Content-Type: application/json" \  -d '{    "profileId": "jd7profile123",    "contacts": [      {        "name": "Jane Doe",        "email": "jane@example.com"      }    ]  }'
{  "message": "Contacts imported successfully",  "created": 1,  "skipped": 1,  "errors": [    "row 3: name is required"  ],  "total": 3}
{  "error": "JSON body is required"}
{  "error": "Unauthorized"}
{  "error": "API key requires read_write permission"}
{  "error": "Not found"}
{  "error": "rate_limited",  "retryAfter": 30}
{  "error": "Failed to create post"}

Create a contact POST

Requires read_write. Limited to 600 creates/hour/user. Creates a contact and optionally its first channel. Maximum 5000 contacts per user and 20 channels per contact. Unknown accounts return 404 accountNotFound; accounts in another profile or platform mismatches return 400 validation. Out-of-scope profiles return 403 forbidden.

Get a contact GET

Requires read_only. Returns the contact with distinct conversationIds and channels, oldest first. Unknown or out-of-scope ids return 404 contactNotFound. Counters start when Contacts ships; history is not backfilled.