Contacts

Update a contact

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.

patch/v1/contacts/{contactId}

Request

Base URL: https://api.postzen.dev
URL: https://api.postzen.dev/v1/contacts/{contactId}
Auth: HTTP bearer

Path parameters

contactIdstring required

Contact owning this channel.

Example:jd7contact123

Request body

namestring

Trimmed contact name, 1–200 characters.

emailstring nullable

Trimmed lowercase email; unique within its profile. Send null to clear.

companystring nullable

Company name, at most 200 characters. Send null to clear.

avatarUrlstring uri nullable

Public HTTPS avatar URL, canonicalized on PATCH; inbox avatars are stored as supplied by the platform. Send null to clear.

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.

isBlockedboolean

Blocked contacts cannot receive comment automation sends.

notesstring nullable

Free-form notes, at most 5000 characters. Send null to clear.

customFieldsobject nullable

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. Send null to clear.

Example request

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

Response

Update a contact.

messagestring required

Operation confirmation.

Example response

{
  "message": "Contact updated 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"
  }
}

Changes

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