> ## Documentation Index
> Fetch the complete documentation index at: https://convo.co.in/docs/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.

## 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

**project\_id** `string` *required*

Your Convo project ID. You can find this in your Convo dashboard under **Project Settings**.

**contact\_id** `string` *required*

The Convo contact ID of the contact to update (e.g., `64f3a1e0c8e4d500123abc00`). You can obtain this from the [Create Contact](https://convo.co.in/docs/api-reference/contacts/create-contact.md) or [Get Contact](https://convo.co.in/docs/api-reference/contacts/get-contact.md) responses.

## Request Body

**name** `string`

Updated display name for the contact. Replaces the existing name.

**opted\_in** `boolean`

Set to `false` to opt this contact **out** of WhatsApp notifications. Set to `true` to re-opt them in.

**blocked** `boolean`

Set to `true` to block this contact. Blocked contacts cannot receive any messages. Set to `false` to unblock them.

**attributes** `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"
}
```

## Examples

**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"
    }
  }'
```

**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
  }'
```

**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"
    }
  }'
```

> [!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.

## 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
}
```

**id** `string`

The Convo contact ID.

**project\_id** `string`

The Convo project this contact belongs to.

**phone\_number** `string`

The contact's WhatsApp phone number (with country code, no `+`).

**name** `string`

The contact's updated display name.

**country\_code** `string`

The numeric country dialing code (e.g., `"91"` for India).

**on\_whatsapp** `boolean`

`true` if the phone number is active on WhatsApp.

**is\_closed** `boolean`

`true` if the conversation with this contact is marked as closed.

**is\_intervened** `boolean`

`true` if a human agent is handling this contact's conversation.

**is\_requesting** `boolean`

`true` if the contact has an active pending request awaiting a human agent response.

**last\_active** `number`

Unix timestamp in milliseconds of the contact's most recent activity.

**tags** `array`

Current list of tags applied to this contact.

**attributes** `object`

The contact's full custom attributes map after the merge update.

**first\_message** `object`

Object containing `id` and `added_at` for the contact's first inbound message.

**created\_at** `number`

Unix timestamp in milliseconds when this contact was originally created.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.