List Contacts

GET /external/v1/contacts

Returns a paginated list of all contacts in your account.

Authentication

Requires contacts:read permission.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number for pagination
limit	integer	50	Items per page (1-100)
search	string	-	Search by name, email, or company
company	string	-	Filter by company name
email	string	-	Filter by email address
phone	string	-	Filter by phone number
source	string	-	Filter by source name/label
tags	string	-	Filter by tag IDs (comma-separated)
created_after	string (ISO 8601)	-	Only contacts created on/after this timestamp
created_before	string (ISO 8601)	-	Only contacts created on/before this timestamp
updated_after	string (ISO 8601)	-	Only contacts updated on/after this timestamp
updated_before	string (ISO 8601)	-	Only contacts updated on/before this timestamp
sort_by	string	created_at	Sort field (created_at, updated_at, name, company, last_interaction)
sort_order	string	desc	Sort order (asc, desc)

Incremental sync

To pull only what changed since your last sync, combine the date filters with sorting: GET /contacts?updated_after=2026-06-08T00:00:00Z&sort_by=updated_at&sort_order=asc. An invalid date returns 400 VALIDATION_ERROR.

Request

cURL

curl --request GET \
  --url "https://app.getraze.com/external/v1/contacts?page=1&limit=50" \
  --header "X-API-Key: YOUR_API_KEY"

Node.js

const axios = require('axios');

const response = await axios.get('https://app.getraze.com/external/v1/contacts', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  params: { page: 1, limit: 50, search: 'john' }
});

console.log(response.data);

Python

import requests

response = requests.get(
    'https://app.getraze.com/external/v1/contacts',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'page': 1, 'limit': 50}
)

print(response.json())

Response

{
  "success": true,
  "data": [
    {
      "id": "cnt_abc123def456",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+5511999999999",
      "company": "Acme Inc",
      "title": "CEO",
      "location": "São Paulo, BR",
      "linkedin_profile_url": "https://linkedin.com/in/johndoe",
      "source": "LinkedIn",
      "source_channel": "linkedin",
      "custom_fields": {},
      "last_interaction": "2026-01-20T14:00:00Z",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:00:00Z",
      "tags": [
        { "id": "tag_01", "name": "prospect", "color": "blue" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Response Fields

Field	Type	Description
id	string	Unique contact identifier
name	string	Full name
email	string	Email address
phone	string	Phone number
company	string	Company name
title	string	Job title/position
location	string	Location
linkedin_profile_url	string	LinkedIn profile URL
source	string	Lead source label
source_channel	string	Source channel (e.g. linkedin, whatsapp)
custom_fields	object	Custom field key-value pairs
last_interaction	string	ISO 8601 timestamp of the last interaction
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp
tags	array	Tag objects (id, name, color)
pagination	object	Pagination metadata (page, per_page, total, total_pages, has_next, has_prev)