Skip to main content
POST
/
api
/
contacts
curl --request POST \ --url https://api.automatechats.com/api/contacts \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "firstName": "John", "lastName": "Doe", "phoneNumber": "9876543210", "countryCode": "+91", "email": "john.doe@example.com" } '
{
  "status": "success",
  "code": 201,
  "message": "Contact created successfully",
  "data": {
    "contact": {
      "id": "65e0bc51c12e4d70834b070e",
      "firstName": "John",
      "lastName": "Doe",
      "chatName": "John Doe",
      "email": "john.doe@example.com",
      "phoneNumber": "9876543210",
      "countryCode": "+91",
      "source": "manual",
      "subscribed": true,
      "tagsId": [
        "65e0bc51c12e4d70834b070e"
      ],
      "tags": [
        {
          "tagId": "65e0bc51c12e4d70834b070e",
          "name": "VIP",
          "text_color": "#ffffff",
          "background_color": "#ef4444"
        }
      ],
      "customFields": [
        {
          "id": "65f12ab3c9e4f1a2b3c4d5e6",
          "label": "Company Name",
          "value": "Google Deepmind"
        }
      ],
      "dob": "1990-01-15",
      "anniversary": "2020-06-20",
      "workspaceId": 246,
      "createdBy": "6996aeeedf12574080a99d81",
      "createdAt": "2026-05-18T15:00:00.000Z",
      "updatedAt": "2026-05-18T15:05:00.000Z"
    }
  },
  "timestamp": "2023-11-07T05:31:56Z"
}
{
  "status": "error",
  "code": 400,
  "message": "Invalid input: field first_name is required.",
  "error": "<unknown>",
  "timestamp": "2026-05-18T15:00:00.000Z"
}
{
  "status": "error",
  "code": 401,
  "message": "Unauthorized access: Invalid or missing authentication credentials.",
  "timestamp": "2026-05-18T15:00:00.000Z"
}
{
  "status": "error",
  "code": 409,
  "message": "Duplicate key error: Contact with this phone number already exists in the workspace.",
  "timestamp": "2026-05-18T15:00:00.000Z"
}
Use this endpoint to add new contacts to your workspace. You must provide a valid phoneNumber and countryCode to create a contact. You can also optionally enrich the contact’s profile with their name, email, tags, and custom fields during creation. The system automatically performs duplicate checks. By default, you cannot create multiple contacts with the same phone number in a single workspace. You can pass overwrite: true to seamlessly update the existing contact’s values instead of receiving a duplication error.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
firstName
string
required

Contact's first name

Required string length: 2 - 50
Example:

"John"

​
phoneNumber
string
required

Phone number without country code (typically 10-15 digits)

Example:

"9876543210"

​
countryCode
string
required

Country code including '+' (e.g. +91, +1)

Example:

"+91"

​
source
string
required

Required source identifier (e.g., contact_form)

Maximum string length: 50
Example:

"contact_form"

​
lastName
string

Contact's last name

Maximum string length: 50
Example:

"Doe"

​
chatName
string

Formatted name used in active chats

Maximum string length: 100
Example:

"John Doe"

​
email
string<email>

Contact's email address

Example:

"john.doe@example.com"

​
subscribed
boolean
default:true

Auto-subscribe contact to WhatsApp broadcasts

​
overwrite
boolean
default:false

If true, updates the existing contact if a contact with the same phone number already exists, instead of returning a duplicate error.

​
tagsId
string[]

Array of 24-character hexadecimal MongoDB Tag IDs to assign

Example:
["65e0bc51c12e4d70834b070e"]
​
customFields
object[]

Array of custom field values to assign

​
dob
string<date>

Date of Birth (YYYY-MM-DD)

Example:

"1990-01-15"

​
anniversary
string<date>

Anniversary date (YYYY-MM-DD)

Example:

"2020-06-20"

Response

Contact created successfully

​
status
string
Example:

"success"

​
code
integer
Example:

201

​
message
string
Example:

"Contact created successfully"

​
data
object
​
timestamp
string<date-time>