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

# 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

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

## Request Body

<ParamField body="name" type="string" required>
  The contact's display name as it will appear in your Convo dashboard and in conversations.
</ParamField>

<ParamField body="mobile_number" type="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).
</ParamField>

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

<ResponseField name="id" type="string">
  The Convo-assigned unique ID for this contact. Use this ID with the [Get Contact](/api-reference/contacts/get-contact), [Update Contact](/api-reference/contacts/update-contact), and messaging endpoints.
</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 display name as provided during creation.
</ResponseField>

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

<ResponseField name="on_whatsapp" type="boolean">
  `true` if the phone number is registered on WhatsApp. Convo verifies this automatically when the contact is created.
</ResponseField>

<ResponseField name="is_closed" type="boolean">
  `true` if the conversation with this contact has been marked as closed in the Convo inbox.
</ResponseField>

<ResponseField name="is_intervened" type="boolean">
  `true` if a human agent has taken over this contact's conversation from the bot or automation.
</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">
  List of tags applied to this contact. Empty array for newly created contacts.
</ResponseField>

<ResponseField name="attributes" type="object">
  Key-value map of custom attributes for this contact. Empty object for newly created contacts. Use [Update Contact](/api-reference/contacts/update-contact) to populate custom attributes.
</ResponseField>

<ResponseField name="first_message" type="object">
  Object containing `id` and `added_at` for the contact's first inbound message. `null` if no messages have been received yet.
</ResponseField>

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

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