> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Contact: Add a New Contact to Your Workspace
> Use POST /api/v1/contacts to add a new contact to your ChatbotX Workspace with a phone number, email address, gender, and optional name fields.
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
The contact's phone number. Must be 10–20 digits and may include a leading `+`. Pattern: `\+?\d{10,20}`.
The contact's email address. Must be a valid email format.
The contact's gender. One of: `male`, `female`, `unknown`.
The contact's first name. Maximum 100 characters.
The contact's last name. Maximum 100 characters.
## Code Examples
```bash curl theme={null}
curl --request POST \
--url https://app.chatbotx.io/api/v1/contacts \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"phoneNumber": "+84708123123",
"email": "jane.doe@example.com",
"gender": "female",
"firstName": "Jane",
"lastName": "Doe"
}'
```
```python Python theme={null}
import requests
url = "https://app.chatbotx.io/api/v1/contacts"
headers = {
"Authorization": "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json"
}
payload = {
"phoneNumber": "+84708123123",
"email": "jane.doe@example.com",
"gender": "female",
"firstName": "Jane",
"lastName": "Doe"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const options = {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phoneNumber: '+84708123123',
email: 'jane.doe@example.com',
gender: 'female',
firstName: 'Jane',
lastName: 'Doe'
})
};
fetch('https://app.chatbotx.io/api/v1/contacts', options)
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```
## Response Fields
Unique contact ID generated by ChatbotX.
Timestamp when the contact was created.
Timestamp of the last update.
URL of the contact's profile image.
Contact's phone number.
Contact's email address.
Whether the email has been verified.
Whether the contact has opted in to email communications.
Contact's first name.
Contact's last name.
Contact's computed full name.
One of `male`, `female`, `unknown`.
When the contact last read a message.
External reference identifier.
Contact's country.
Contact's state or region.
Contact's city.
Contact's locale string.
Contact's timezone.
When the contact subscribed.
When the contact subscribed to broadcasts.
When the contact was blocked, or `null`.
The Workspace this contact belongs to.
Custom field values assigned to the contact.
Tags applied to the contact.
Notes attached to the contact.
Inbox connections for this contact.
Most recent conversation, or `null`.
## Example Response
```json theme={null}
{
"id": "clx2def456",
"createdAt": "2024-01-15T09:00:00Z",
"updatedAt": "2024-01-15T09:00:00Z",
"avatar": null,
"phoneNumber": "+84708123123",
"email": "jane.doe@example.com",
"emailVerified": false,
"emailOptIn": false,
"firstName": "Jane",
"lastName": "Doe",
"fullName": "Jane Doe",
"gender": "female",
"lastReadAt": null,
"ref": null,
"country": null,
"state": null,
"city": null,
"location": null,
"locale": null,
"timezone": null,
"subscribedAt": null,
"broadcastSubscribedAt": null,
"blockedAt": null,
"workspaceId": "ws123",
"contactCustomFields": [],
"tags": [],
"contactNotes": [],
"contactInboxes": [],
"conversation": null
}
```