PostZen
Contacts

List contacts

GET
/v1/contacts

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.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Query Parameters

profileId?string

Owning profile id; immutable and must be in the API key scope.

accountId?string

Connected account id; must belong to the same profile and caller.

search?string

Case-insensitive substring search across name, email and company.

tag?string

Match this tag case-insensitively; combined with tags using any-match semantics.

tags?string

Comma-separated tags; a contact matching any supplied tag is included.

platform?string

PostZen platform. Always resolved from the connected account.

isSubscribed?string

Filter by contact subscription state.

limit?integer

Page size, an integer from 1 to 200; invalid values return 400.

skip?integer

Number of matching rows to skip, a nonnegative integer.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts?profileId=jd7profile123&accountId=jd7account123&search=jane&tag=VIP&tags=VIP%2CLead&platform=instagram&isSubscribed=true&limit=50&skip=0"
{  "contacts": [    {      "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",      "platform": "instagram",      "platformIdentifier": "178414000001",      "displayIdentifier": "@jane",      "channelCount": 1    }  ],  "filters": {    "tags": [      "Lead",      "VIP"    ]  },  "pagination": {    "total": 1,    "limit": 50,    "skip": 0,    "hasMore": false  }}
{  "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"}

List comment automation logs GET

Newest logs first. total is capped at 5000 matching rows. Misses are not logged. Out-of-scope ids return 404 automationNotFound. Instagram only. A comment permits one private reply ever, within 7 days. Story replies use normal DMs inside the 24-hour messaging window. Buttons and image cards (template) fall back to text with title and URL lines if Meta rejects the template. Reconnect the account on 403 platformCapabilityMissing to grant instagram_business_manage_comments and instagram_business_manage_messages.

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.