Create a contact

Creates a contact (WhatsApp customer) by phone.

Creates a contact (WhatsApp customer) by phone. Scope: crm.

Required: phone (international format). Optional: name, email, city, country, owner_user_id, lifecycle_stage_id (see …/schema), company_id, custom_fields (keyed by field key).

A phone that already exists answers 409 with code: already_exists and that contact in data.

WhatsApp usernames (only for workspaces with WhatsApp username support switched on; absent otherwise). phone keeps its meaning.

whatsapp_bsuid — Meta's ID for a customer who hides their number behind a WhatsApp username, e.g. EG.2288384708632117. Not a phone number; null when Meta sent none.
whatsapp_username — the customer's WhatsApp @username, without the @. Display only; null when none.
phone_available — false when the customer keeps their number private: do not SMS, call or store phone as a number.

JSON body

{
  "phone": "+966500000000",
  "name": "Ahmed Ali",
  "email": "ahmed@example.com",
  "city": "Riyadh",
  "country": "SA",
  "lifecycle_stage_id": 2,
  "company_id": 7,
  "custom_fields": {
    "source_campaign": "spring_sale"
  }
}

Example request

curl -X POST "https://your-workspace.letsbot.net/api/v1/crm/contacts" \
  -H "X-Zapier-Api-Key: YOUR_WORKSPACE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+966500000000",
  "name": "Ahmed Ali",
  "email": "ahmed@example.com",
  "city": "Riyadh",
  "country": "SA",
  "lifecycle_stage_id": 2,
  "company_id": 7,
  "custom_fields": {
    "source_campaign": "spring_sale"
  }
}'

const response = await fetch("https://your-workspace.letsbot.net/api/v1/crm/contacts", {
  method: "POST",
  headers: {
    "X-Zapier-Api-Key": "YOUR_WORKSPACE_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "phone": "+966500000000",
    "name": "Ahmed Ali",
    "email": "ahmed@example.com",
    "city": "Riyadh",
    "country": "SA",
    "lifecycle_stage_id": 2,
    "company_id": 7,
    "custom_fields": {
      "source_campaign": "spring_sale"
    }
  }),
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://your-workspace.letsbot.net/api/v1/crm/contacts');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Zapier-Api-Key: YOUR_WORKSPACE_API_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
    {
        "phone": "+966500000000",
        "name": "Ahmed Ali",
        "email": "ahmed@example.com",
        "city": "Riyadh",
        "country": "SA",
        "lifecycle_stage_id": 2,
        "company_id": 7,
        "custom_fields": {
            "source_campaign": "spring_sale"
        }
    }
    JSON,
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($data);

import requests

response = requests.request(
    "POST",
    "https://your-workspace.letsbot.net/api/v1/crm/contacts",
    headers={
        "X-Zapier-Api-Key": "YOUR_WORKSPACE_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+966500000000",
        "name": "Ahmed Ali",
        "email": "ahmed@example.com",
        "city": "Riyadh",
        "country": "SA",
        "lifecycle_stage_id": 2,
        "company_id": 7,
        "custom_fields": {
            "source_campaign": "spring_sale",
        },
    },
)

print(response.json())

Responses

Created201

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Ahmed Ali",
    "phone": "966500000000",
    "email": "ahmed@example.com",
    "city": "Riyadh",
    "country": "SA",
    "lifecycle": {
      "id": 2,
      "name": "Lead"
    },
    "owner": {
      "id": 3,
      "name": "Sara Ahmed"
    },
    "company": {
      "id": 7,
      "name": "Example Trading Co."
    },
    "tags": [
      "vip"
    ],
    "custom_fields": {
      "source_campaign": "spring_sale"
    },
    "last_activity_at": "2026-10-08T09:30:00+03:00",
    "created_at": "2026-10-01T12:00:00+03:00",
    "updated_at": "2026-10-08T09:30:00+03:00",
    "url": "https://your-workspace.letsbot.net/panel/v2/crm/contacts/42",
    "whatsapp_bsuid": null,
    "whatsapp_username": "ahmed_store",
    "phone_available": true
  }
}

Phone already exists409

{
  "success": false,
  "error": "A contact with this phone already exists.",
  "code": "already_exists",
  "data": {
    "id": 42,
    "name": "Ahmed Ali",
    "phone": "966500000000",
    "email": "ahmed@example.com",
    "city": "Riyadh",
    "country": "SA",
    "lifecycle": {
      "id": 2,
      "name": "Lead"
    },
    "owner": {
      "id": 3,
      "name": "Sara Ahmed"
    },
    "company": {
      "id": 7,
      "name": "Example Trading Co."
    },
    "tags": [
      "vip"
    ],
    "custom_fields": {
      "source_campaign": "spring_sale"
    },
    "last_activity_at": "2026-10-08T09:30:00+03:00",
    "created_at": "2026-10-01T12:00:00+03:00",
    "updated_at": "2026-10-08T09:30:00+03:00",
    "url": "https://your-workspace.letsbot.net/panel/v2/crm/contacts/42",
    "whatsapp_bsuid": null,
    "whatsapp_username": "ahmed_store",
    "phone_available": true
  }
}

Validation failed422

{
  "success": false,
  "error": "The phone field is required.",
  "code": "validation_failed",
  "errors": {
    "phone": [
      "The phone field is required."
    ]
  }
}

Ready when you are

Try this endpoint on your own number

The API works during the free trial. Create an account, connect your WhatsApp number and copy your key from API → Authentication Data.

Start your free trial All endpoints

Create a contact

Related endpoints

Try this endpoint on your own number