Contacts Overview

Manage customer profiles, segmentation tags, custom metadata, and bulk ingestion in Sayvy AI

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 serve as the primary audience foundation for outbound WhatsApp campaigns and Voice AI telephony dispatching.

+-------------------------------------------------------------+
|                      Sayvy AI Contact                       |
|                                                             |
|  +-----------------+  +-----------------+  +--------------+ |
|  |  Identity Data  |  |  Segmentation   |  | Custom Meta  | |
|  |  * Phone Number |  |  * Tags         |  | * JSON dict  | |
|  |  * Full Name    |  |  * Lists        |  | * Notes      | |
|  +--------+--------+  +--------+--------+  +-------+------+ |
|           \                    |                   /        |
|            +-------------------+------------------+         |
|                                |                            |
|                                v                            |
|              +----------------------------------+           |
|              |     Campaign & Voice Target      |           |
|              |  (WhatsApp Broadcasts / Calls)  |           |
|              +----------------------------------+           |
+-------------------------------------------------------------+

---

Key Capabilities

Individual Contact Management

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

Dynamic Segmentation

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

Arbitrary Custom Fields

Store extensible JSON key-value data (e.g. account_id, company, tier) for dynamic template variable interpolation.

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. [phone]).
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.
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 all contacts for your organization
PUT	/api/v1/contacts/{contact_id}	Update an existing contact’s details and tags
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 ›