Skip to main content
The Contacts API allows you to create, read, update, and delete contacts.

​
Endpoints Overview

MethodEndpointDescription
GET/v1/contactsList contacts
POST/v1/contactsCreate contact
GET/v1/contacts/:idGet contact
PATCH/v1/contacts/:idUpdate contact
DELETE/v1/contacts/:idDelete contact
POST/v1/contacts/importImport from CSV
GET/v1/contacts/searchSearch contacts
POST/v1/contacts/normalizeNormalize phone number
POST/v1/dncAdd to DNC list

​
List Contacts

GET /v1/contacts?workspaceId=ws_abc123&limit=20&offset=0
Authorization: Bearer <access_token>
Response: 
{
  "data": [
    {
      "id": "contact_123",
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+14155551234",
      "email": "john@example.com",
      "company": "Acme Inc",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "hasMore": true
  }
}

​
Create Contact

POST /v1/contacts
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "workspaceId": "ws_abc123",
  "firstName": "John",
  "lastName": "Smith",
  "phone": "+14155551234",
  "email": "john@example.com",
  "company": "Acme Inc"
}

​
Update Contact

PATCH /v1/contacts/:id
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "firstName": "Jane",
  "notes": "Interested in premium plan"
}

​
Delete Contact

DELETE /v1/contacts/:id
Authorization: Bearer <access_token>

​
Search Contacts

POST /v1/contacts/search
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "workspaceId": "ws_abc123",
  "query": "John Smith",
  "filters": {
    "company": "Acme Inc"
  },
  "limit": 10
}

​
Normalize Phone Number

POST /v1/contacts/normalize
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "phone": "(415) 555-1234"
}
Response: 
{
  "data": {
    "original": "(415) 555-1234",
    "normalized": "+14155551234",
    "isValid": true,
    "countryCode": "US",
    "areaCode": "415"
  }
}

​
Do Not Call (DNC)

Add a number to the DNC list: 
POST /v1/dnc
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "workspaceId": "ws_abc123",
  "phone": "+14155551234",
  "reason": "Customer request"
}