Create Contact

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.

Create a contact with a full phone number

If you only have one number that already includes the country code, use POST /api/contacts/create-with-phone. You send the full number in phoneNumber and we detect the country code. Don’t send countryCode. If you do, the request is rejected.

This endpoint updates the contact if it already exists. Fields you leave out stay unchanged, and customFields are merged. Send "overwrite": false to get a 409 duplicate error instead.

curl --location 'https://api.automatechats.com/api/contacts/create-with-phone' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "919876543210",
  "email": "john.doe@example.com"
}'

The contact is saved with country code 91 and phone number 9876543210.

Request body

Field	Type	Required	Description
`firstName`	string	Yes	2 to 50 characters.
`phoneNumber`	string	Yes	Full number with country code, such as `919876543210`, `+919876543210`, or `00919876543210`. Spaces and dashes are allowed.
`lastName`	string	No	Up to 50 characters.
`chatName`	string	No	Up to 100 characters.
`email`	string	No	A valid email address.
`source`	string	No	Up to 50 characters.
`subscribed`	boolean	No	Whether the contact receives broadcasts.
`tagsId`	string[]	No	Tag IDs to assign.
`customFields`	array	No	Objects with `fieldId` and `value`.
`dob`	string	No	Date of birth, `YYYY-MM-DD`.
`anniversary`	string	No	Anniversary date, `YYYY-MM-DD`.
`overwrite`	boolean	No	Defaults to `true`. Set `false` to return a `409` if the contact already exists.

Responses

The success response has the same shape as the POST /api/contacts response. A new contact returns 201.

Code	Meaning
`400`	The country code couldn’t be detected, a field is invalid, or `countryCode` was sent.
`401`	The API key is missing or invalid.
`409`	The contact already exists and `overwrite` is `false`.

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"

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

Show child attributes

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

Show child attributes

timestamp

string<date-time>

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"
}

Getting Started

Core Features

API Reference

Create a contact with a full phone number

Request body

Responses

Authorizations

Body

Response

​Create a contact with a full phone number

​Request body

​Responses

Authorizations

Body

Response

Create a contact with a full phone number

Request body

Responses