POST — Add WhatsApp Contact

Import one or more WhatsApp contacts into BotPenguin. Use this API to create new contacts or update existing ones with profile details including name, email, phone, tags, and custom attributes.

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.

[
  {
    "profile": {
      "userDetails": {
        "userProvidedName": "John Doe",
        "contact": {
          "email": "[e-mail]",
          "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

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": "[e-mail]",
            "phone": {
              "number": "9876543210",
              "prefix": "91"
            }
          },
          "tags": ["lead", "demo"],
          "attributes": [
            { "key": "plan", "value": "pro" }
          ]
        }
      }
    }
  ]'

---

Response

Success — 200 OK

{
  "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:

{
  "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 [e-mail]