Skip to main content

​
Overview

The Contacts API allows you to import, 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" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDescription
statusstringFilter by status: active, dnc
searchstringSearch by name, phone, or email
campaign_idstringFilter by campaign membership
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20, max: 100)

​
Response

{
  "data": [
    {
      "id": "contact_abc123",
      "phone": "+15551234567",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "company": "Acme Corp",
      "title": "Manager",
      "status": "active",
      "calls_count": 3,
      "last_called_at": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-10T09:00:00Z"
    }
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 20
  }
}

​
Get Contact

Retrieve a single contact with call history. 
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",
    "title": "Manager",
    "status": "active",
    "metadata": {
      "source": "website",
      "interest": "enterprise"
    },
    "calls": [
      {
        "id": "call_xyz789",
        "direction": "outbound",
        "status": "completed",
        "duration": 180,
        "sentiment": "positive",
        "created_at": "2024-01-15T14:30:00Z"
      }
    ],
    "campaigns": [
      {
        "id": "campaign_def456",
        "name": "January Outreach",
        "status": "completed"
      }
    ],
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

​
Create Contact

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

​
Parameters

ParameterTypeRequiredDescription
phonestringYesPhone number (E.164 format recommended)
first_namestringNoFirst name
last_namestringNoLast name
emailstringNoEmail address
companystringNoCompany name
titlestringNoJob title
metadataobjectNoCustom key-value data

​
Response

{
  "data": {
    "id": "contact_new789",
    "phone": "+15551234567",
    "first_name": "John",
    "last_name": "Smith",
    "status": "active",
    "created_at": "2024-01-16T10:00:00Z"
  }
}

​
Import Contacts (Bulk)

Import multiple contacts at once. 
curl -X POST "https://api.getsmartalex.com/v1/contacts/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone": "+15551234567",
        "first_name": "John",
        "last_name": "Smith"
      },
      {
        "phone": "+15559876543",
        "first_name": "Jane",
        "last_name": "Doe"
      }
    ],
    "skip_duplicates": true
  }'

​
Parameters

ParameterTypeRequiredDescription
contactsarrayYesArray of contact objects (max 1000)
skip_duplicatesbooleanNoSkip duplicate phone numbers (default: true)
update_existingbooleanNoUpdate existing contacts (default: false)

​
Response

{
  "data": {
    "imported": 2,
    "duplicates_skipped": 0,
    "invalid_skipped": 0,
    "errors": []
  }
}
For imports larger than 1000 contacts, make multiple requests or contact support for bulk import options.

​
Update Contact

Update an existing contact’s information. 
curl -X PUT "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
phonestringPhone number
first_namestringFirst name
last_namestringLast name
emailstringEmail address
companystringCompany name
titlestringJob title
statusstringactive or dnc
metadataobjectCustom data (merged with existing)

​
Response

{
  "data": {
    "id": "contact_abc123",
    "phone": "+15551234567",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@newcompany.com",
    "company": "New Company Inc",
    "status": "active",
    "updated_at": "2024-01-16T10:30:00Z"
  }
}

​
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

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

​
Mark as DNC

Add a contact to the Do Not Call list. 
curl -X POST "https://api.getsmartalex.com/v1/contacts/contact_abc123/dnc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "contact_abc123",
    "status": "dnc",
    "dnc_at": "2024-01-16T10:00:00Z"
  }
}

​
Remove from DNC

Remove a contact from the Do Not Call list. 
curl -X DELETE "https://api.getsmartalex.com/v1/contacts/contact_abc123/dnc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "contact_abc123",
    "status": "active"
  }
}

​
Contact Status

StatusDescription
activeAvailable to be called
dncDo Not Call - will not be dialed

​
Error Codes

CodeDescription
contact_not_foundContact ID doesn’t exist
duplicate_phonePhone number already exists
invalid_phonePhone number format is invalid
contact_limit_reachedPlan contact limit exceeded
import_too_largeImport exceeds maximum batch size