Contacts

List 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.

get/v1/contacts

Request

  • Base URL: https://api.postzen.dev
  • URL: https://api.postzen.dev/v1/contacts
  • Auth: HTTP bearer

Query parameters

profileIdstring

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

Example:jd7profile123
accountIdstring

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

Example:jd7account123
searchstring

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

Example:jane
tagstring

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

Example:VIP
tagsstring

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

Example:VIP,Lead
platform'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram'

PostZen platform. Always resolved from the connected account.

Example:instagram
isSubscribed'true' | 'false'

Filter by contact subscription state.

Example:true
limitinteger

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

Example:50
skipinteger

Number of matching rows to skip, a nonnegative integer.

Response

List contacts.

Example response

{
  "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
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.