Skip to main content
The Create Contact endpoint adds a new contact record to your Workspace. At minimum, you must supply a phone number, an email address, and a gender value. You can optionally provide a first name and last name. The response returns the complete contact object, including generated IDs, timestamps, and all related sub-resources.
POST /api/v1/contacts

Request Body

string
required
The contact’s phone number. Must be 10–20 digits and may include a leading +. Pattern: \+?\d{10,20}.
string
required
The contact’s email address. Must be a valid email format.
string
required
The contact’s gender. One of: male, female, unknown.
string
The contact’s first name. Maximum 100 characters.
string
The contact’s last name. Maximum 100 characters.

Code Examples

Response Fields

string
required
Unique contact ID generated by ChatbotX.
string (date-time)
required
Timestamp when the contact was created.
string (date-time)
required
Timestamp of the last update.
string | null
required
URL of the contact’s profile image.
string | null
required
Contact’s phone number.
string | null
required
Contact’s email address.
boolean
required
Whether the email has been verified.
boolean
required
Whether the contact has opted in to email communications.
string | null
required
Contact’s first name.
string | null
required
Contact’s last name.
string | null
required
Contact’s computed full name.
string | null
required
One of male, female, unknown.
string (date-time) | null
required
When the contact last read a message.
string | null
required
External reference identifier.
string | null
required
Contact’s country.
string | null
required
Contact’s state or region.
string | null
required
Contact’s city.
string | null
required
Contact’s locale string.
string | null
required
Contact’s timezone.
string (date-time) | null
required
When the contact subscribed.
string (date-time) | null
required
When the contact subscribed to broadcasts.
string (date-time) | null
required
When the contact was blocked, or null.
string
required
The Workspace this contact belongs to.
array
required
Custom field values assigned to the contact.
array
required
Tags applied to the contact.
array
required
Notes attached to the contact.
array
required
Inbox connections for this contact.
object | null
required
Most recent conversation, or null.

Example Response