Skip to main content
Create a contact. Phone numbers are unique per workspace; emails are also unique per workspace when provided.

​
Endpoint

POST /api/v1/{subdomain}/contacts
Required ability: contacts.create.

​
Headers

HeaderValue
AuthorizationBearer apitk_...
Content-Typeapplication/json
Acceptapplication/json

​
Path parameters

​
subdomain
string
required
Your workspace subdomain.

​
Body parameters

​
firstname
string
required
First name. Max 255 characters. Note the spelling — firstname, not first_name.
​
lastname
string
Last name. Max 255 characters. Optional on create (required on update).
​
phone
string
required
Phone number. Max 20 characters. Unique per workspace.
​
email
string
Email address. Max 191 characters. When provided, must be unique per workspace.
​
type
string
required
Contact type. Must be lead or customer. (The underlying enum also permits guest, but the API does not accept it.)
​
source_id
integer
required
Id of an existing Source in your workspace.
​
status_id
integer
required
Id of an existing Status in your workspace.
​
company
string
Company name. Max 255 characters.
​
description
string
Freeform description.
​
country_id
integer
Country id.
​
assigned_id
integer
User id of the owner.
​
groups
string
Comma-separated group names. Groups that do not exist are auto-created.

​
Example request

curl -X POST https://dash.xobito.com/api/v1/acme/contacts \
  -H "Authorization: Bearer apitk_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+14155551234",
    "email": "john@example.com",
    "type": "lead",
    "source_id": 2,
    "status_id": 1,
    "groups": "VIP,Newsletter"
  }'

​
Example response

201 Created
{
  "status": "success",
  "message": "Contact created successfully",
  "data": {
    "id": 451,
    "tenant_id": 13,
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+14155551234",
    "email": "john@example.com",
    "type": "lead",
    "source_id": 2,
    "status_id": 1,
    "group_id": [7, 8],
    "is_enabled": 1,
    "is_opted_out": 0,
    "created_at": "2026-04-16T12:00:00.000000Z",
    "updated_at": "2026-04-16T12:00:00.000000Z"
  }
}
See Data Types → Contact for every field.

​
Error responses

StatusWhenExample body
401Missing / invalid token{"status":"error","message":"API token is required"}
403Missing ability{"status":"error","message":"Token does not have the required ability: contacts.create"}
403Plan limit hit{"status":"error","message":"Contact limit exceeded for your current plan. Upgrade to add more contacts."}
422Validation{"status":"error","message":"Validation failed","errors":{"phone":["The phone has already been taken."]}}
429Rate limit{"message":"Too many requests","retry_after":45}
500Server error{"status":"error","message":"Failed to create contact"}