> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/contacts-and-chats-apis/post-add-whatsapp-contact.md).

# POST — Add WhatsApp Contact

### Overview

| Property          | Details                                            |
| ----------------- | -------------------------------------------------- |
| **Method**        | `POST`                                             |
| **Endpoint**      | `https://api.v7.botpenguin.com/inbox/users/import` |
| **Base URL**      | `https://api.v7.botpenguin.com`                    |
| **API Version**   | v7                                                 |
| **Auth Required** | Yes — Bearer Token                                 |
| **Content-Type**  | `application/json`                                 |

***

### Authentication

| Header          | Required | Value                   |
| --------------- | -------- | ----------------------- |
| `Authorization` | ✅ Yes    | `Bearer [MASKED_TOKEN]` |
| `authtype`      | ✅ Yes    | `Key`                   |

***

### Request

#### Headers

| Header          | Required | Value                   |
| --------------- | -------- | ----------------------- |
| `Authorization` | ✅ Yes    | `Bearer [MASKED_TOKEN]` |
| `authtype`      | ✅ Yes    | `Key`                   |
| `Content-Type`  | ✅ Yes    | `application/json`      |

***

#### Request Body

The request body is a **JSON array** of contact objects. Each object represents one contact to import. Multiple contacts can be imported in a single request.

```json
[
  {
    "profile": {
      "userDetails": {
        "userProvidedName": "John Doe",
        "contact": {
          "email": "john@example.com",
          "phone": {
            "number": "9876543210",
            "prefix": "91"
          }
        },
        "tags": ["lead", "demo"],
        "attributes": [
          { "key": "plan", "value": "pro" }
        ]
      }
    }
  }
]
```

**Body Fields**

The body is an **array** — wrap even a single contact in `[]`.

| Field                                      | Type     | Required | Description                                                                                   |
| ------------------------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `profile`                                  | `object` | ✅ Yes    | Wrapper object for the contact's profile data.                                                |
| `profile.userDetails`                      | `object` | ✅ Yes    | Contact details object.                                                                       |
| `profile.userDetails.userProvidedName`     | `string` | ✅ Yes    | Full name of the contact.                                                                     |
| `profile.userDetails.contact`              | `object` | ✅ Yes    | Contact information wrapper.                                                                  |
| `profile.userDetails.contact.email`        | `string` | ✅ Yes    | Email address of the contact. Pass `""` if not available.                                     |
| `profile.userDetails.contact.phone`        | `object` | ✅ Yes    | Phone number object.                                                                          |
| `profile.userDetails.contact.phone.number` | `string` | ✅ Yes    | Phone number without country code.                                                            |
| `profile.userDetails.contact.phone.prefix` | `string` | ✅ Yes    | Country dial code without `+`. Example: `91` for India, `1` for USA.                          |
| `profile.userDetails.tags`                 | `array`  | ✅ Yes    | Labels to assign to the contact. Pass `[]` if none.                                           |
| `profile.userDetails.attributes`           | `array`  | ✅ Yes    | Custom key-value pairs. Each entry must contain `key` and `value` strings. Pass `[]` if none. |

***

#### Example Request

```bash
curl 'https://api.v7.botpenguin.com/inbox/users/import' \
  -X POST \
  -H 'Authorization: Bearer [MASKED_TOKEN]' \
  -H 'authtype: Key' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    {
      "profile": {
        "userDetails": {
          "userProvidedName": "John Doe",
          "contact": {
            "email": "john@example.com",
            "phone": {
              "number": "9876543210",
              "prefix": "91"
            }
          },
          "tags": ["lead", "demo"],
          "attributes": [
            { "key": "plan", "value": "pro" }
          ]
        }
      }
    }
  ]'
```

***

### Response

#### Success — `200 OK`

```json
{
  "success": true,
  "message": "success",
  "code": 200
}
```

**Response Fields**

| Field     | Type      | Description                                              |
| --------- | --------- | -------------------------------------------------------- |
| `success` | `boolean` | `true` if the import was accepted.                       |
| `message` | `string`  | Status message. Value: `"success"` on successful import. |
| `code`    | `number`  | HTTP status code echo. `200` on success.                 |

***

### HTTP Status Codes

| Code  | Status                | Meaning                                                |
| ----- | --------------------- | ------------------------------------------------------ |
| `200` | OK                    | Import accepted successfully.                          |
| `400` | Bad Request           | Malformed request body or missing required fields.     |
| `401` | Unauthorized          | Bearer token is missing, invalid, or expired.          |
| `429` | Too Many Requests     | Rate limit exceeded. Retry after the indicated window. |
| `500` | Internal Server Error | Server-side error. Contact support if it persists.     |

***

### Error Handling

All errors return a consistent structure:

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Bearer token is invalid or has expired.",
    "statusCode": 401
  }
}
```

***

### Rate Limits

This endpoint is limited to **100 requests per minute** per token, across all plans. Exceeding this returns `429 Too Many Requests`. Use the `Retry-After` response header (in seconds) to schedule your retry.

***

*For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)