Contacts

Create a contact

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.

post/v1/contacts

Request

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

Request body

profileIdstring required

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

namestring required

Trimmed contact name, 1–200 characters.

emailstring

Trimmed lowercase email; unique within its profile.

companystring

Company name, at most 200 characters.

tagsstring[]

At most 50 tags, trimmed and deduplicated case-insensitively, preserving original case. Send [] to clear.

isSubscribedboolean

Contact subscription state. False prevents comment automation sends.

notesstring

Free-form notes, at most 5000 characters.

customFieldsobject

At most 50 keys of 1–64 characters. Keys follow Convex record rules: printable ASCII, not starting with $ or _. Values are strings (at most 1000 characters), finite numbers, booleans, or null. PATCH replaces the entire object.

accountIdstring

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

platformIdentifierstring

Platform identity (IGSID, PSID, or handle), trimmed, 1–200 characters. Unique per connected account.

displayIdentifierstring

Optional username or friendly handle, at most 200 characters. Without a channel it is ignored and a warning is returned.

platform'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram'

Optional assertion of the account platform. Must equal account.platform; requires accountId and platformIdentifier.

Example request

{
  "profileId": "jd7profile123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "company": "Acme",
  "tags": [
    "VIP",
    "Lead"
  ],
  "isSubscribed": true,
  "notes": "Interested in the launch.",
  "customFields": {
    "leadScore": 42,
    "customer": true
  },
  "accountId": "jd7account123",
  "platformIdentifier": "178414000001",
  "displayIdentifier": "@jane",
  "platform": "instagram"
}

Response

Create a contact.

messagestring required

Operation confirmation.

warningstring

Included only when displayIdentifier was supplied without a channel.

Example response

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

Changes

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