Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getsmartalex.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Contacts API allows you to create, update, and manage contacts in your SmartAlex database.

​
List Contacts

Get all contacts with optional filtering. 
curl -X GET "https://api.getsmartalex.com/v1/contacts?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20)

​
Response

{
  "data": [
    {
      "id": "contact_abc123",
      "phone": "+15551234567",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "company": "Acme Corp",
      "tags": ["lead", "enterprise"],
      "status": "active",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 20
  }
}

​
Get Contact

Retrieve a single contact by ID. 
curl -X GET "https://api.getsmartalex.com/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "contact_abc123",
    "phone": "+15551234567",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "company": "Acme Corp",
    "tags": ["lead", "enterprise"],
    "status": "active",
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-01-15T14:30:00Z"
  }
}

​
Create Contact

Add a single contact to your database. first_name is required. 
curl -X POST "https://api.getsmartalex.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+15551234567",
    "email": "john@example.com",
    "company": "Acme Corp",
    "tags": ["lead"]
  }'

​
Parameters

ParameterTypeRequiredDescription
first_namestringYesFirst name
last_namestringNoLast name
phonestringNoPhone number (E.164 format recommended)
emailstringNoEmail address
companystringNoCompany name
tagsarray of stringsNoTags for filtering and segmentation
statusstringNoactive (default) or dnc

​
Response (201 Created)

{
  "id": "contact_new789",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+15551234567",
  "email": "john@example.com",
  "company": "Acme Corp",
  "tags": ["lead"],
  "status": "active",
  "created_at": "2026-04-28T10:00:00Z"
}

​
Update Contact

Update an existing contact’s information. Only include the fields you want to change. 
curl -X PATCH "https://api.getsmartalex.com/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.smith@newcompany.com",
    "company": "New Company Inc"
  }'

​
Parameters

All parameters are optional. Only included fields will be updated.
ParameterTypeDescription
first_namestringFirst name
last_namestringLast name
phonestringPhone number
emailstringEmail address
companystringCompany name
tagsarray of stringsTags
statusstringactive or dnc

​
Delete Contact

Remove a contact from your database. 
curl -X DELETE "https://api.getsmartalex.com/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "deleted": true
}
Deleting a contact removes them from all campaigns and deletes their call history association.

​
Marking a contact as Do Not Call

To mark a contact as Do Not Call, update their status field to "dnc": 
curl -X PATCH "https://api.getsmartalex.com/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "dnc" }'
To remove a contact from the DNC list, set status back to "active".

​
Contact Status

StatusDescription
activeAvailable to be called
dncDo Not Call — will not be dialled in any campaign

​
Bulk import via CSV

For bulk imports, use the dashboard’s CSV upload flow under Contacts → Import. The dashboard supports up to 1000 contacts per upload with column mapping and duplicate detection. For larger imports, contact support.

​
Error Codes

CodeDescription
contact_not_foundContact ID doesn’t exist
invalid_phonePhone number format is invalid