List contacts

GET

api

contacts

curl -X GET "https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&ai_handling=true&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

import requests

url = "https://api.sayvy.ai/api/v1/contacts"

params = {
    "lifecycle_stage": "qualified",
    "ai_handling": "true",
    "page": 1,
    "page_size": 20
}

headers = {
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

const params = new URLSearchParams({
  lifecycle_stage: "qualified",
  ai_handling: "true",
  page: "1",
  page_size: "20"
});

const response = await fetch(`https://api.sayvy.ai/api/v1/contacts?${params.toString()}`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
console.log(data);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&page=1&page_size=20"))
    .header("Authorization", "Bearer <token>")
    .GET()
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "contacts": [
    {
      "id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
      "organization_id": "00000000-0000-0000-0000-000000000001",
      "phone_number": "+14155550199",
      "name": "Jane Doe",
      "tags": [
        "vip",
        "enterprise"
      ],
      "notes": "Met at SaaS Summit 2026",
      "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
      },
      "lifecycle_stage": "qualified",
      "lead_score": 85,
      "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "ai_handling": true,
      "last_activity_at": "2026-10-07T14:30:00Z",
      "source": "manual",
      "created_at": "2026-10-07T11:00:00Z",
      "updated_at": "2026-10-07T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "has_more": false
}

{
  "detail": "Unauthorized"
}

Returns a paginated list of contacts for your organization. Supports advanced CRM query filtering including search terms, lifecycle stages, assigned owners, AI handling delegation, lead scores, classification tags, and activity recency.

Authentication

This endpoint requires Bearer token authentication.

Authorization: Bearer <token>

Header	Type	Required	Description	Format
`Authorization`	`string`	Yes	Scoped organization API key or Bearer JWT token	`Bearer <token>`

Query Parameters

string

required

Bearer token for authentication. Format: Bearer <token>.

integer

default:"1"

Page number for pagination (starts at 1).

integer

default:"50"

Number of contacts per page (minimum 1, maximum 100).

integer

Alternative alias for page_size (minimum 1, maximum 100).

string

Search term matching contact names or telephone numbers.

string

Filter by CRM lifecycle stage (new, engaged, qualified, customer, lost).

string

Filter by assigned owner user UUID.

boolean

Filter by AI handling state (true for AI automated, false for human agent).

integer

Filter contacts with lead score greater than or equal to this integer (0–100).

integer

Filter contacts with lead score less than or equal to this integer (0–100).

string

Filter contacts having a specific classification tag (e.g. vip).

string

Filter contacts active before this ISO 8601 datetime (e.g. 2026-10-01T00:00:00Z).

Response Fields

ContactResponse[]

Array of contact objects:

Show Contact item attributes

string

Contact UUID.

string

Organization UUID.

string

Destination telephone number.

string

Contact display name.

string[]

Assigned classification tags.

string

Internal notes text.

object

Arbitrary metadata key-value dictionary.

string

Lifecycle pipeline stage (new, engaged, qualified, customer, lost).

integer

Lead score integer (0–100).

string

Assigned team member UUID or null.

boolean

Whether AI handles interactions (true) or human (false).

string

ISO 8601 timestamp of last interaction.

string

Origin source (manual, bulk_upload, inbound_call).

string

ISO 8601 creation timestamp.

string

ISO 8601 modification timestamp.

integer

Total count of contacts matching query filters.

integer

Current page number.

integer

Number of items per page.

boolean

Flag indicating whether additional pages of results are available.

curl -X GET "https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&ai_handling=true&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

import requests

url = "https://api.sayvy.ai/api/v1/contacts"

params = {
    "lifecycle_stage": "qualified",
    "ai_handling": "true",
    "page": 1,
    "page_size": 20
}

headers = {
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

const params = new URLSearchParams({
  lifecycle_stage: "qualified",
  ai_handling: "true",
  page: "1",
  page_size: "20"
});

const response = await fetch(`https://api.sayvy.ai/api/v1/contacts?${params.toString()}`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
console.log(data);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&page=1&page_size=20"))
    .header("Authorization", "Bearer <token>")
    .GET()
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "contacts": [
    {
      "id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
      "organization_id": "00000000-0000-0000-0000-000000000001",
      "phone_number": "+14155550199",
      "name": "Jane Doe",
      "tags": [
        "vip",
        "enterprise"
      ],
      "notes": "Met at SaaS Summit 2026",
      "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
      },
      "lifecycle_stage": "qualified",
      "lead_score": 85,
      "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "ai_handling": true,
      "last_activity_at": "2026-10-07T14:30:00Z",
      "source": "manual",
      "created_at": "2026-10-07T11:00:00Z",
      "updated_at": "2026-10-07T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "has_more": false
}

{
  "detail": "Unauthorized"
}

‹ Previous

Get contact

GET /api/v1/contacts/{contact_id}

Next ›

curl -X GET "https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&ai_handling=true&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

import requests

url = "https://api.sayvy.ai/api/v1/contacts"

params = {
    "lifecycle_stage": "qualified",
    "ai_handling": "true",
    "page": 1,
    "page_size": 20
}

headers = {
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

const params = new URLSearchParams({
  lifecycle_stage: "qualified",
  ai_handling: "true",
  page: "1",
  page_size: "20"
});

const response = await fetch(`https://api.sayvy.ai/api/v1/contacts?${params.toString()}`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();
console.log(data);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts?lifecycle_stage=qualified&page=1&page_size=20"))
    .header("Authorization", "Bearer <token>")
    .GET()
    .build();

HttpResponse<String> response =
    HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "contacts": [
    {
      "id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
      "organization_id": "00000000-0000-0000-0000-000000000001",
      "phone_number": "+14155550199",
      "name": "Jane Doe",
      "tags": [
        "vip",
        "enterprise"
      ],
      "notes": "Met at SaaS Summit 2026",
      "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
      },
      "lifecycle_stage": "qualified",
      "lead_score": 85,
      "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "ai_handling": true,
      "last_activity_at": "2026-10-07T14:30:00Z",
      "source": "manual",
      "created_at": "2026-10-07T11:00:00Z",
      "updated_at": "2026-10-07T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "has_more": false
}

{
  "detail": "Unauthorized"
}

Overview

Agents

Campaigns

Contacts

CRM

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Authentication

Query Parameters

Response Fields

​Authentication

​Query Parameters

​Response Fields

Authentication

Query Parameters

Response Fields