> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# PATCH /project/{project_id}/contact/{id} — Update Contact

> PATCH /project/{project_id}/contact/{id} — Update a contact's name, custom attributes, opt-in status, or blocked status in Convo.

Use this endpoint to update one or more fields on an existing contact. You can change their display name, manage their opt-in or blocked status, and set or update custom attributes.

<Note>
  This is a **partial update** (PATCH semantics). Only the fields you include in the request body will be modified. Any fields you omit remain unchanged. You do not need to send the full contact object.
</Note>

## Endpoint

```text theme={null}
PATCH https://connect.api-wa.co/project-apis/v1/project/{project_id}/contact/{contact_id}
```

## Authentication

Include your project API password in every request header:

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

<ParamField path="project_id" type="string" required>
  Your Convo project ID. You can find this in your Convo dashboard under **Project Settings**.
</ParamField>

<ParamField path="contact_id" type="string" required>
  The Convo contact ID of the contact to update (e.g., `64f3a1e0c8e4d500123abc00`). You can obtain this from the [Create Contact](/api-reference/contacts/create-contact) or [Get Contact](/api-reference/contacts/get-contact) responses.
</ParamField>

## Request Body

<ParamField body="name" type="string">
  Updated display name for the contact. Replaces the existing name.
</ParamField>

<ParamField body="opted_in" type="boolean">
  Set to `false` to opt this contact **out** of WhatsApp notifications. Set to `true` to re-opt them in.
</ParamField>

<ParamField body="blocked" type="boolean">
  Set to `true` to block this contact. Blocked contacts cannot receive any messages. Set to `false` to unblock them.
</ParamField>

<ParamField body="attributes" type="object">
  Key-value pairs of custom attributes to set or update on the contact. This is a **merge operation** — new keys are added, and existing keys are updated. Keys not present in the request are left unchanged.

  Example:

  ```json theme={null}
  {
    "plan": "premium",
    "city": "Mumbai",
    "signup_date": "2024-01-15"
  }
  ```
</ParamField>

## Examples

<Tabs>
  <Tab title="Update Attributes">
    Update a contact's name and set custom attributes:

    ```bash theme={null}
    curl -X PATCH \
      "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
      -H "Content-Type: application/json" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -d '{
        "name": "Priya Sharma",
        "attributes": {
          "plan": "premium",
          "city": "Mumbai",
          "signup_date": "2024-01-15"
        }
      }'
    ```
  </Tab>

  <Tab title="Opt Out Contact">
    Opt a contact out of WhatsApp notifications:

    ```bash theme={null}
    curl -X PATCH \
      "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
      -H "Content-Type: application/json" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -d '{
        "opted_in": false
      }'
    ```
  </Tab>

  <Tab title="Full Update">
    Update multiple fields in a single request:

    ```bash theme={null}
    curl -X PATCH \
      "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact/64f3a1e0c8e4d500123abc00" \
      -H "Content-Type: application/json" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -d '{
        "name": "Priya Sharma",
        "opted_in": false,
        "blocked": false,
        "attributes": {
          "plan": "premium",
          "city": "Mumbai",
          "signup_date": "2024-01-15"
        }
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  **Opting out a contact is significant.** Once `opted_in` is set to `false`, you **cannot send proactive messages** (template/HSM messages) to that contact until they opt back in. Only inbound-initiated session messages can be exchanged within an active 24-hour conversation window. Make sure you have the contact's consent before modifying this field.
</Warning>

## Response

**200 OK** — Returns the full updated contact object.

```json theme={null}
{
  "id": "64f3a1e0c8e4d500123abc00",
  "project_id": "YOUR_PROJECT_ID",
  "phone_number": "917089379345",
  "name": "Priya Sharma",
  "country_code": "91",
  "on_whatsapp": true,
  "is_closed": false,
  "is_intervened": false,
  "is_requesting": false,
  "last_active": 1710050000000,
  "tags": ["vip", "newsletter"],
  "attributes": {
    "plan": "premium",
    "city": "Mumbai",
    "signup_date": "2024-01-15"
  },
  "first_message": {
    "id": "msg_001",
    "added_at": 1710000500000
  },
  "created_at": 1710000000000
}
```

<ResponseField name="id" type="string">
  The Convo contact ID.
</ResponseField>

<ResponseField name="project_id" type="string">
  The Convo project this contact belongs to.
</ResponseField>

<ResponseField name="phone_number" type="string">
  The contact's WhatsApp phone number (with country code, no `+`).
</ResponseField>

<ResponseField name="name" type="string">
  The contact's updated display name.
</ResponseField>

<ResponseField name="country_code" type="string">
  The numeric country dialing code (e.g., `"91"` for India).
</ResponseField>

<ResponseField name="on_whatsapp" type="boolean">
  `true` if the phone number is active on WhatsApp.
</ResponseField>

<ResponseField name="is_closed" type="boolean">
  `true` if the conversation with this contact is marked as closed.
</ResponseField>

<ResponseField name="is_intervened" type="boolean">
  `true` if a human agent is handling this contact's conversation.
</ResponseField>

<ResponseField name="is_requesting" type="boolean">
  `true` if the contact has an active pending request awaiting a human agent response.
</ResponseField>

<ResponseField name="last_active" type="number">
  Unix timestamp in milliseconds of the contact's most recent activity.
</ResponseField>

<ResponseField name="tags" type="array">
  Current list of tags applied to this contact.
</ResponseField>

<ResponseField name="attributes" type="object">
  The contact's full custom attributes map after the merge update.
</ResponseField>

<ResponseField name="first_message" type="object">
  Object containing `id` and `added_at` for the contact's first inbound message.
</ResponseField>

<ResponseField name="created_at" type="number">
  Unix timestamp in milliseconds when this contact was originally created.
</ResponseField>

## Error Responses

| HTTP Status | Meaning                                                              |
| ----------- | -------------------------------------------------------------------- |
| `400`       | Bad request — invalid field value or request body format.            |
| `401`       | Unauthorized — invalid or missing `X-API-WA-Project-API-Pwd` header. |
| `404`       | Contact not found — the `contact_id` does not exist in this project. |