Create contact

POST

api

contacts

curl -X POST "https://api.sayvy.ai/api/v1/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
      "company": "Acme Corp",
      "deal_size": 25000
    }
  }'

import requests

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

payload = {
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
    }
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    phone_number: "+14155550199",
    name: "Jane Doe",
    tags: ["vip", "enterprise"],
    notes: "Met at SaaS Summit 2026",
    custom_fields: {
      company: "Acme Corp",
      deal_size: 25000
    }
  })
});

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;

String jsonPayload = """
{
  "phone_number": "+14155550199",
  "name": "Jane Doe",
  "tags": ["vip", "enterprise"],
  "notes": "Met at SaaS Summit 2026",
  "custom_fields": {
    "company": "Acme Corp"
  }
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

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

{
  "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": "new",
  "lead_score": 0,
  "owner_id": null,
  "ai_handling": true,
  "last_activity_at": "2026-10-07T11:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T11:00:00Z"
}

{
  "detail": "Invalid phone number format or length."
}

{
  "detail": "Unauthorized"
}

Create a new contact record with phone number, name, optional categorization tags, notes, and custom metadata fields. The contact is initialized with default CRM attributes (lifecycle_stage: "new", lead_score: 0, and ai_handling: true).

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>`

Input parameters

The following parameters are accepted in the JSON request body.

string

required

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

string

required

Destination phone number (maximum 50 characters). E.164 format is recommended (e.g. +14155550199).

string

required

Full name or display name of the contact (maximum 255 characters). Example: Jane Doe.

string[]

Array of classification tags for segmenting campaigns (e.g. ["lead", "vip", "retail"]). Defaults to [].

string

Internal context, notes, or customer history notes.

object

Key-value dictionary containing arbitrary custom metadata (e.g. {"account_id": "acc_123", "plan": "enterprise"}).

Response Fields

string

Generated UUID identifier of the contact.

string

UUID of the owning organization.

string

Contact’s telephone number.

string

Contact’s full name.

string[]

Assigned segmentation tags.

string

Internal notes text or null.

object

Stored custom metadata object or null.

string

Current CRM lifecycle stage (new, engaged, qualified, customer, lost). Initialized to new.

integer

Numerical qualification score between 0 and 100. Default is 0.

string

UUID of assigned user/team member or null.

boolean

Flag determining whether AI voice & chat agents handle interactions (true) or human agents (false). Default is true.

string

ISO 8601 timestamp of last recorded activity, or null.

string

Origin attribution of contact or null.

string

ISO 8601 creation timestamp.

string

ISO 8601 last modification timestamp.

curl -X POST "https://api.sayvy.ai/api/v1/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
      "company": "Acme Corp",
      "deal_size": 25000
    }
  }'

import requests

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

payload = {
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
    }
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    phone_number: "+14155550199",
    name: "Jane Doe",
    tags: ["vip", "enterprise"],
    notes: "Met at SaaS Summit 2026",
    custom_fields: {
      company: "Acme Corp",
      deal_size: 25000
    }
  })
});

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;

String jsonPayload = """
{
  "phone_number": "+14155550199",
  "name": "Jane Doe",
  "tags": ["vip", "enterprise"],
  "notes": "Met at SaaS Summit 2026",
  "custom_fields": {
    "company": "Acme Corp"
  }
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

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

{
  "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": "new",
  "lead_score": 0,
  "owner_id": null,
  "ai_handling": true,
  "last_activity_at": "2026-10-07T11:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T11:00:00Z"
}

{
  "detail": "Invalid phone number format or length."
}

{
  "detail": "Unauthorized"
}

‹ Previous

List contacts

GET /api/v1/contacts

Next ›

curl -X POST "https://api.sayvy.ai/api/v1/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
      "company": "Acme Corp",
      "deal_size": 25000
    }
  }'

import requests

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

payload = {
    "phone_number": "+14155550199",
    "name": "Jane Doe",
    "tags": ["vip", "enterprise"],
    "notes": "Met at SaaS Summit 2026",
    "custom_fields": {
        "company": "Acme Corp",
        "deal_size": 25000
    }
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

const response = await fetch("https://api.sayvy.ai/api/v1/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    phone_number: "+14155550199",
    name: "Jane Doe",
    tags: ["vip", "enterprise"],
    notes: "Met at SaaS Summit 2026",
    custom_fields: {
      company: "Acme Corp",
      deal_size: 25000
    }
  })
});

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;

String jsonPayload = """
{
  "phone_number": "+14155550199",
  "name": "Jane Doe",
  "tags": ["vip", "enterprise"],
  "notes": "Met at SaaS Summit 2026",
  "custom_fields": {
    "company": "Acme Corp"
  }
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

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

{
  "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": "new",
  "lead_score": 0,
  "owner_id": null,
  "ai_handling": true,
  "last_activity_at": "2026-10-07T11:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T11:00:00Z"
}

{
  "detail": "Invalid phone number format or length."
}

{
  "detail": "Unauthorized"
}

Overview

Agents

Campaigns

Contacts

CRM

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Authentication

Input parameters

Response Fields

​Authentication

​Input parameters

​Response Fields

Authentication

Input parameters

Response Fields