Skip to main content
GET
/
api
/
v1
/
contacts
curl "https://api.usegately.com/api/v1/contacts?status=active&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID"

{
  "contacts": [
    {
      "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
      "project_id": "proj-uuid-here",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "status": "active",
      "unsubscribed": false,
      "tags": [
        { "id": "tag-uuid", "name": "VIP", "color": "#ff6600" }
      ],
      "custom_fields": { "plan": "pro" },
      "last_contacted_at": "2025-05-10T09:00:00.000Z",
      "created_at": "2025-01-15T12:00:00.000Z",
      "updated_at": "2025-05-10T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}

​
Headers

​
Authorization
string
required
Bearer YOUR_API_KEY
​
X-Project-ID
string
Your project UUID. Not required if the API key already encodes the project.

​
Query Parameters

​
page
number
default:"1"
Page number
​
limit
number
default:"50"
Results per page (max 200)
​
search
string
Search by name, email, or company
​
status
string
Filter by status: new · active · inactive · archived
​
tags
string
Comma-separated tag names to filter by (e.g. VIP,Newsletter)
​
segment_id
string
Return only contacts that match a specific segment

​
Response

​
contacts
Contact[]
Array of contact objects with resolved tags
​
pagination
object
curl "https://api.usegately.com/api/v1/contacts?status=active&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID"

{
  "contacts": [
    {
      "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
      "project_id": "proj-uuid-here",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "status": "active",
      "unsubscribed": false,
      "tags": [
        { "id": "tag-uuid", "name": "VIP", "color": "#ff6600" }
      ],
      "custom_fields": { "plan": "pro" },
      "last_contacted_at": "2025-05-10T09:00:00.000Z",
      "created_at": "2025-01-15T12:00:00.000Z",
      "updated_at": "2025-05-10T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}