Contacts API

The Contacts API enables you to programmatically manage your organization’s address book, customer phone numbers, segment tags, internal notes, and arbitrary custom key-value attributes. Contacts also integrate deeply with the CRM engine, supporting lifecycle stages, lead scoring, AI/human handling delegation, and a chronological activity timeline.

+---------------------------------------------------------------------------------+
|                               Sayvy AI Contact                                  |
|                                                                                 |
|  +-----------------+  +-----------------+  +--------------+  +---------------+  |
|  |  Identity Data  |  |  Segmentation   |  | Custom Meta  |  |  CRM & Status |  |
|  |  * Phone Number |  |  * Tags         |  | * JSON dict  |  |  * Stage      |  |
|  |  * Full Name    |  |  * Lists        |  | * Notes      |  |  * Lead Score |  |
|  |                 |  |                 |  |              |  |  * AI/Human   |  |
|  +--------+--------+  +--------+--------+  +-------+------+  +-------+-------+  |
|           \                    |                   /                 /          |
|            +-------------------+------------------+-----------------+           |
|                                |                                                |
|                                v                                                |
|              +----------------------------------+                               |
|              |     Campaign & Voice Target      |                               |
|              |  (WhatsApp Broadcasts / Calls)  |                               |
|              +-----------------+----------------+                               |
|                                |                                                |
|                                v                                                |
|              +----------------------------------+                               |
|              |    Activity Timeline & Tasks     |                               |
|              | (Notes, Messages, Handoffs, CRM) |                               |
|              +----------------------------------+                               |
+---------------------------------------------------------------------------------+

Key Capabilities

Individual Contact Management

Create, get, update, and delete individual customer records with phone numbers, names, and notes.

CRM Lifecycle & Lead Scoring

Track customer progression across stages (new, engaged, qualified, customer, lost) and automated lead scores (0–100).

AI & Human Handoff Control

Toggle ai_handling flags per contact to smoothly route conversations between automated AI agents and human support staff.

Chronological Activity Timeline

Audit all customer touchpoints including inbound/outbound messages, stage updates, agent handoffs, and internal notes.

Dynamic Segmentation

Assign string tags (e.g. vip, trial_user, q3_leads) to power selective campaign targeting.

High-Speed Bulk Ingestion

Upload CSV or Excel spreadsheets containing thousands of contacts with automated duplicate updating and validation error reporting.

Contact Model Schema

Each contact in Sayvy AI is scoped to your organization and contains:

Field	Type	Description
`id`	`UUID`	Unique contact identifier.
`organization_id`	`UUID`	Owning organization identifier.
`phone_number`	`string`	Customer phone number (E.164 format recommended, e.g. `+14155550123`).
`name`	`string`	Full name of the contact.
`tags`	`string[]`	Array of classification tags used in campaign audience filters.
`notes`	`string`	Internal agent or administrative notes.
`custom_fields`	`object`	Arbitrary JSON metadata for custom integration logic.
`lifecycle_stage`	`string`	Current pipeline stage: `new`, `engaged`, `qualified`, `customer`, or `lost`. Default is `new`.
`lead_score`	`integer`	Numerical lead qualification score from `0` to `100`. Default is `0`.
`owner_id`	`UUID`	ID of the assigned team member or user (optional).
`ai_handling`	`boolean`	When `true`, Voice and Chat AI handle interactions automatically. When `false`, routed to human agents.
`last_activity_at`	`string`	ISO 8601 timestamp of the most recent interaction or activity event.
`source`	`string`	Origin source of the contact (e.g. `manual`, `bulk_upload`, `inbound_call`).
`created_at`	`string`	ISO 8601 creation timestamp.
`updated_at`	`string`	ISO 8601 last update timestamp.

Multi-Tenant Security & Isolation

All contact operations are strictly isolated by organization context. Attempting to update or delete a contact ID belonging to another organization returns a 404 Not Found response to avoid leaking identifier existence.

Available Endpoints

Method	Endpoint	Description
POST	`/api/v1/contacts`	Create a new contact record manually
GET	`/api/v1/contacts`	List contacts with CRM filtering (stage, owner, score, tag) and pagination
GET	`/api/v1/contacts/{contact_id}`	Retrieve a single contact by unique ID
PUT	`/api/v1/contacts/{contact_id}`	Update standard contact details (name, phone, tags, custom fields)
PATCH	`/api/v1/contacts/{contact_id}`	Partially update CRM attributes (stage, lead score, owner, AI handling)
GET	`/api/v1/contacts/{contact_id}/activities`	Retrieve chronological activity timeline for a contact
POST	`/api/v1/contacts/{contact_id}/activities`	Log a manual note or activity event against a contact
DELETE	`/api/v1/contacts/{contact_id}`	Permanently delete a contact
POST	`/api/v1/contacts/bulk-upload`	Bulk upload contacts via CSV or Excel spreadsheets

‹ Previous

Create contact

POST /api/v1/contacts

Next ›

Overview

Agents

Campaigns

Contacts

CRM

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Contacts Overview

Contacts API

Key Capabilities

Individual Contact Management

CRM Lifecycle & Lead Scoring

AI & Human Handoff Control

Chronological Activity Timeline

Dynamic Segmentation

High-Speed Bulk Ingestion

Contact Model Schema

Multi-Tenant Security & Isolation

Available Endpoints

​Contacts API

​Key Capabilities

Individual Contact Management

CRM Lifecycle & Lead Scoring

AI & Human Handoff Control

Chronological Activity Timeline

Dynamic Segmentation

High-Speed Bulk Ingestion

​Contact Model Schema

​Multi-Tenant Security & Isolation

​Available Endpoints

Contacts API

Key Capabilities

Contact Model Schema

Multi-Tenant Security & Isolation

Available Endpoints