Create a contact

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

Header	Value
`Authorization`	`Bearer <your-64-hex-token>`
`Content-Type`	`application/json`
`Accept`	`application/json`

Path parameters

string

required

Your workspace subdomain.

Body parameters

string

required

First name. Max 255 characters. Note the spelling — firstname, not first_name.

string

Last name. Max 255 characters. Optional on create (required on update).

string

required

Phone number. Max 20 characters. Unique per workspace.

string

Email address. Max 191 characters. When provided, must be unique per workspace.

string

required

Contact type. Must be lead or customer. (The underlying enum also permits guest, but the API does not accept it.)

integer

required

Id of an existing Source in your workspace.

integer

required

Id of an existing Status in your workspace.

string

Company name. Max 255 characters.

string

Freeform description.

integer

Country id.

integer

User id of the owner.

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 <your_token>" \
  -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"
  }'

const res = await fetch("https://dash.xobito.com/api/v1/acme/contacts", {
  method: "POST",
  headers: {
    Authorization: "Bearer <your_token>",
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  body: JSON.stringify({
    firstname: "John",
    lastname: "Doe",
    phone: "+14155551234",
    email: "john@example.com",
    type: "lead",
    source_id: 2,
    status_id: 1,
    groups: "VIP,Newsletter",
  }),
});
const body = await res.json();

import requests

r = requests.post(
    "https://dash.xobito.com/api/v1/acme/contacts",
    headers={
        "Authorization": "Bearer <your_token>",
        "Accept": "application/json",
    },
    json={
        "firstname": "John",
        "lastname": "Doe",
        "phone": "+14155551234",
        "email": "john@example.com",
        "type": "lead",
        "source_id": 2,
        "status_id": 1,
        "groups": "VIP,Newsletter",
    },
)
body = r.json()

<?php
$ch = curl_init('https://dash.xobito.com/api/v1/acme/contacts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <your_token>',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'firstname' => 'John',
        'lastname'  => 'Doe',
        'phone'     => '+14155551234',
        'email'     => 'john@example.com',
        'type'      => 'lead',
        'source_id' => 2,
        'status_id' => 1,
        'groups'    => 'VIP,Newsletter',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

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

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

Introduction

API Reference

Webhooks

Data Types

Create a contact

Endpoint

Headers

Path parameters

Body parameters

Example request

Example response

Error responses

​Endpoint

​Headers

​Path parameters

​Body parameters

​Example request

​Example response

​Error responses

Endpoint

Headers

Path parameters

Body parameters

Example request

Example response

Error responses