PostZen
Contacts

Get a contact

GET
/v1/contacts/{contactId}

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.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Path Parameters

contactId*string

Contact owning this channel.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/jd7contact123"
{  "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",    "conversationIds": [      "t_12345"    ]  },  "channels": [    {      "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"    }  ]}
{  "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"}

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.

Update a contact PATCH

Requires read_write. Limited to 600 updates/hour/user. Supports partial updates, null clears for email, company, avatarUrl, notes and customFields, and [] to clear tags. customFields replaces the entire object. profileId and channel fields cannot be changed. Unknown or out-of-scope ids return 404 contactNotFound.