---
title: "Update a contact"
method: PATCH
path: "/v1/contacts/{contactId}"
tags: ["Contacts"]
---

# Update a contact

`PATCH /v1/contacts/{contactId}`

## Request

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

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.

## Path parameters

- `contactId` string, required: Contact owning this channel.

## Request body

- ContactUpdateRequest: Partial update. profileId cannot be changed; channel fields and unknown keys are rejected with 400 validation. Tags replace the array and customFields replaces the whole object.
  - `name` string: Trimmed contact name, 1–200 characters.
  - `email` string, nullable: Trimmed lowercase email; unique within its profile. Send null to clear.
  - `company` string, nullable: Company name, at most 200 characters. Send null to clear.
  - `avatarUrl` string, uri, nullable: Public HTTPS avatar URL, canonicalized on PATCH; inbox avatars are stored as supplied by the platform. Send null to clear.
  - `tags` string[]: At most 50 tags, trimmed and deduplicated case-insensitively, preserving original case. Send [] to clear.
  - `isSubscribed` boolean: Contact subscription state. False prevents comment automation sends.
  - `isBlocked` boolean: Blocked contacts cannot receive comment automation sends.
  - `notes` string, nullable: Free-form notes, at most 5000 characters. Send null to clear.
  - `customFields` object, 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.

## Response `200`

Update a contact.

- object
  - `message` string, required: Operation confirmation.
  - `contact` Contact, required: A profile-owned person. Maximum 5000 contacts per user and 20 channels per contact. Absent optional fields are returned as null. Message history is not backfilled.
    - `id` string, required: Contact id.
    - `profileId` string, required: Owning profile id; immutable and must be in the API key scope.
    - `name` string, required: Trimmed contact name, 1–200 characters.
    - `email` string, nullable, required: Trimmed lowercase email; unique within its profile.
    - `company` string, nullable, required: Company name, at most 200 characters.
    - `avatarUrl` string, uri, nullable, required: Public HTTPS avatar URL, canonicalized on PATCH; inbox avatars are stored as supplied by the platform.
    - `tags` string[], required: At most 50 tags, trimmed and deduplicated case-insensitively, preserving original case. Send [] to clear.
    - `isSubscribed` boolean, required: Contact subscription state. False prevents comment automation sends.
    - `isBlocked` boolean, required: Blocked contacts cannot receive comment automation sends.
    - `notes` string, nullable, required: Free-form notes, at most 5000 characters.
    - `customFields` object, nullable, required: 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.
    - `messagesSentCount` integer, required: Messages sent by the connected account, including automation DMs. Counters start when Contacts ships; history is not backfilled.
    - `messagesReceivedCount` integer, required: Messages received from this person since Contacts ships; re-syncing stored messages does not increment this count.
    - `lastMessageSentAt` string, date-time, nullable, required: Latest counted outbound message time, or null.
    - `lastMessageReceivedAt` string, date-time, nullable, required: Latest counted inbound message time, or null.
    - `source` 'api' | 'inbox' | 'automation', required: How this contact first came to exist; informational and immutable.
    - `createdAt` string, date-time, required: Contact creation time.
    - `updatedAt` string, date-time, required: Latest contact update time.

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `403`: The API key does not have sufficient permission or profile access.
- `404`: Resource not found.
- `409`: duplicateContact: email already belongs to another contact in the same profile.
- `429`: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)