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

# POST /project/{project_id}/contact — Create Contact

> POST /project/{project_id}/contact — Add a new contact to your Convo project. New contacts are automatically opted in for WhatsApp notifications.

Creates a new contact in your Convo project and automatically opts them in for WhatsApp notifications. Once created, you can send messages to the contact and manage them through the Convo dashboard or API.

## Endpoint

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

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

## Request Body

**name** `string` *required*

The contact's display name as it will appear in your Convo dashboard and in conversations.

**mobile\_number** `string` *required*

The contact's WhatsApp phone number including the country code. Do **not** include a leading `+` sign. Example: `917089379345` for an Indian number (+91 70893 79345).

## Example Request

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/contact" \
  -H "Content-Type: application/json" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -d '{
    "name": "Priya Sharma",
    "mobile_number": "917089379345"
  }'
```

## Response

**200 OK** — Returns the full contact object for the newly created contact.

```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": 1710000000000,
  "tags": [],
  "attributes": {},
  "first_message": null,
  "created_at": 1710000000000
}
```

## Response Fields

**id** `string`

The Convo-assigned unique ID for this contact. Use this ID with the [Get Contact](https://convo.co.in/docs/api-reference/contacts/get-contact.md), [Update Contact](https://convo.co.in/docs/api-reference/contacts/update-contact.md), and messaging endpoints.

**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 display name as provided during creation.

**country\_code** `string`

The numeric country dialing code extracted from the phone number (e.g., `"91"` for India).

**on\_whatsapp** `boolean`

`true` if the phone number is registered on WhatsApp. Convo verifies this automatically when the contact is created.

**is\_closed** `boolean`

`true` if the conversation with this contact has been marked as closed in the Convo inbox.

**is\_intervened** `boolean`

`true` if a human agent has taken over this contact's conversation from the bot or automation.

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

List of tags applied to this contact. Empty array for newly created contacts.

**attributes** `object`

Key-value map of custom attributes for this contact. Empty object for newly created contacts. Use [Update Contact](https://convo.co.in/docs/api-reference/contacts/update-contact.md) to populate custom attributes.

**first\_message** `object`

Object containing `id` and `added_at` for the contact's first inbound message. `null` if no messages have been received yet.

**created\_at** `number`

Unix timestamp in milliseconds when the contact was created.

## Error Responses

| HTTP Status | Meaning |
| - | - |
| `400` | Bad request — `name` or `mobile_number` is missing, or the phone number format is invalid. |
| `401` | Unauthorized — invalid or missing `X-API-WA-Project-API-Pwd` header. |
| `404` | Project not found — check your `project_id`. |
| `409` | Conflict — a contact with this phone number already exists in the project. |


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