Contacts API

Connect my tools3 min readUpdated 2026-03-12

Contacts API

The Contacts API lets you keep your JustCall contact list synchronized with your CRM, database, or any external system. You can create, read, update, and delete individual contacts, run filtered searches, and import contacts in bulk.

Endpoints

Method	Endpoint	Description
GET	`/v2/contacts`	List and search contacts
GET	`/v2/contacts/{id}`	Get a single contact
POST	`/v2/contacts`	Create a contact
PUT	`/v2/contacts/{id}`	Update a contact
DELETE	`/v2/contacts/{id}`	Delete a contact
POST	`/v2/contacts/bulk`	Bulk import contacts

Create a Contact

curl -X POST "https://api.justcall.io/v2/contacts" \
  -H "Authorization: {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Lee",
    "phone": "+14155559876",
    "email": "jordan@example.com",
    "company": "Acme Corp",
    "custom_fields": {
      "lead_source": "Website",
      "plan_tier": "Enterprise"
    }
  }'

Response

{
  "status": "success",
  "data": {
    "id": 98765,
    "first_name": "Jordan",
    "last_name": "Lee",
    "phone": "+14155559876",
    "email": "jordan@example.com",
    "company": "Acme Corp",
    "custom_fields": {
      "lead_source": "Website",
      "plan_tier": "Enterprise"
    },
    "created_at": "2026-03-12T14:30:00Z"
  }
}

Search and Filter Contacts

curl -X GET "https://api.justcall.io/v2/contacts?search=jordan&company=Acme+Corp&page=1&per_page=25" \
  -H "Authorization: {api_key}:{api_secret}"

Parameter	Type	Description
`search`	string	Search across name, phone, and email fields
`phone`	string	Filter by exact phone number (E.164)
`email`	string	Filter by exact email address
`company`	string	Filter by company name
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Update a Contact

curl -X PUT "https://api.justcall.io/v2/contacts/98765" \
  -H "Authorization: {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Acme Corp International",
    "custom_fields": {
      "plan_tier": "Premium"
    }
  }'

Only the fields you include in the request body are updated. Omitted fields remain unchanged.

Delete a Contact

curl -X DELETE "https://api.justcall.io/v2/contacts/98765" \
  -H "Authorization: {api_key}:{api_secret}"

Deletion is permanent and cannot be undone.

Bulk Import Contacts

Upload up to 5,000 contacts in a single request:

curl -X POST "https://api.justcall.io/v2/contacts/bulk" \
  -H "Authorization: {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"first_name": "Jordan", "last_name": "Lee", "phone": "+14155559876"},
      {"first_name": "Sam", "last_name": "Chen", "phone": "+14155558765"}
    ]
  }'

The response includes a summary of created, updated (matched by phone number), and failed records.

Custom Fields

You can store arbitrary key-value pairs in the custom_fields object. Custom field keys must be strings. Define custom fields in Settings → Contacts → Custom Fields before using them via the API.