PostZen
Contacts

Create a contact

POST
/v1/contacts

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.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Creates a contact and optionally its first channel. If accountId, platformIdentifier, or platform is supplied, both accountId and platformIdentifier are required. Maximum 5000 contacts per user, 20 channels per contact. Duplicate email within the profile or duplicate channel returns 409.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/contacts" \  -H "Content-Type: application/json" \  -d '{    "profileId": "jd7profile123",    "name": "Jane Doe"  }'
{  "message": "Contact created successfully",  "contact": {    "id": "jd7contact123",    "profileId": "jd7profile123",    "name": "Jane Doe",    "email": "jane@example.com",    "company": "Acme",    "avatarUrl": "https://images.example.com/jane.jpg",    "tags": [      "VIP",      "Lead"    ],    "isSubscribed": true,    "isBlocked": false,    "notes": "Interested in the launch.",    "customFields": {      "leadScore": 42,      "customer": true    },    "messagesSentCount": 3,    "messagesReceivedCount": 5,    "lastMessageSentAt": "2026-09-19T12:00:00.000Z",    "lastMessageReceivedAt": "2026-09-19T12:00:00.000Z",    "source": "api",    "createdAt": "2026-09-19T12:00:00.000Z",    "updatedAt": "2026-09-19T12:00:00.000Z"  },  "channel": {    "id": "jd7channel123",    "contactId": "jd7contact123",    "accountId": "jd7account123",    "platform": "instagram",    "platformIdentifier": "178414000001",    "displayIdentifier": "@jane",    "isSubscribed": true,    "conversationId": "t_12345",    "metadata": {      "locale": "en"    },    "lastActiveAt": "2026-09-19T12:00:00.000Z",    "createdAt": "2026-09-19T12:00:00.000Z"  },  "warning": "displayIdentifier ignored: no channel was created"}
{  "error": "JSON body is required"}
{  "error": "Unauthorized"}
{  "error": "API key requires read_write permission"}
{  "error": "Not found"}
{  "error": "string",  "type": "string",  "code": "string",  "param": "string"}
{  "error": "rate_limited",  "retryAfter": 30}
{  "error": "Failed to create post"}

List contacts GET

Returns contacts in the API key scope, newest first. Requires read_only. Search matches name, email or company. Tag filters use any match. Account and platform filters use contact channels. filters.tags always covers the unfiltered in-scope set. Reads use the plan per-minute budget.

Bulk create contacts POST

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.