Partially update contact CRM

PATCH

api

contacts

{contact_id}

curl -X PATCH "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": false,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  }'

import requests

url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"

payload = {
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": False,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
}

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

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

const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    lifecycle_stage: "qualified",
    lead_score: 90,
    ai_handling: false,
    owner_id: "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  })
});

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 = """
{
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "ai_handling": false
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", 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 Miller",
  "tags": [
    "vip"
  ],
  "notes": "Handoff to enterprise sales team",
  "custom_fields": {
    "company": "Acme Corp"
  },
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "ai_handling": false,
  "last_activity_at": "2026-10-07T16:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T16:00:00Z"
}

{
  "detail": "Contact not found"
}

{
  "detail": "Unauthorized"
}

Partially update CRM pipeline attributes on a contact record, including lifecycle stage transitions, lead scoring adjustments, owner reassignments, and AI handling delegation. Whenever lifecycle stages, scores, or AI handling settings change, the system automatically appends an audit event to the contact’s activity timeline (such as stage_changed, lead_score_changed, handoff_to_human, or handoff_to_ai).

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

string

required

Unique UUID identifier of the contact. Example: 7b8f9e2a-4c1d-48ef-9123-bcde456789ab.

string

required

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

string

Target CRM lifecycle stage: new, engaged, qualified, customer, or lost.

integer

Numerical lead score between 0 and 100.

string

UUID of the assigned team member, or null to unassign.

boolean

Toggle between automated AI engine handling (true) or human agent takeover (false).

string

Updated full name of the contact.

string[]

Updated array of classification tags.

string

Updated internal notes.

object

Updated custom metadata attributes dictionary.

Response Fields

Returns the updated ContactResponse object:

string

Contact UUID.

string

Organization UUID.

string

Telephone number.

string

Updated contact name.

string[]

Updated classification tags.

string

Updated notes text.

object

Updated metadata object.

string

Updated lifecycle stage (new, engaged, qualified, customer, lost).

integer

Updated lead qualification score (0–100).

string

Assigned owner UUID or null.

boolean

Current AI handling status.

string

Timestamp of the newly registered activity.

string

Contact origin.

string

Creation timestamp.

string

Modification timestamp.

curl -X PATCH "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": false,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  }'

import requests

url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"

payload = {
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": False,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
}

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

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

const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    lifecycle_stage: "qualified",
    lead_score: 90,
    ai_handling: false,
    owner_id: "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  })
});

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 = """
{
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "ai_handling": false
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", 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 Miller",
  "tags": [
    "vip"
  ],
  "notes": "Handoff to enterprise sales team",
  "custom_fields": {
    "company": "Acme Corp"
  },
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "ai_handling": false,
  "last_activity_at": "2026-10-07T16:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T16:00:00Z"
}

{
  "detail": "Contact not found"
}

{
  "detail": "Unauthorized"
}

‹ Previous

Get contact activities

GET /api/v1/contacts/{contact_id}/activities

Next ›

curl -X PATCH "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": false,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  }'

import requests

url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"

payload = {
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": False,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
}

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

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

const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    lifecycle_stage: "qualified",
    lead_score: 90,
    ai_handling: false,
    owner_id: "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  })
});

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 = """
{
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "ai_handling": false
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", 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 Miller",
  "tags": [
    "vip"
  ],
  "notes": "Handoff to enterprise sales team",
  "custom_fields": {
    "company": "Acme Corp"
  },
  "lifecycle_stage": "qualified",
  "lead_score": 90,
  "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "ai_handling": false,
  "last_activity_at": "2026-10-07T16:00:00Z",
  "source": "manual",
  "created_at": "2026-10-07T11:00:00Z",
  "updated_at": "2026-10-07T16:00:00Z"
}

{
  "detail": "Contact not found"
}

{
  "detail": "Unauthorized"
}

Overview

Agents

Campaigns

Contacts

CRM

Templates

Knowledge Base

Webhooks

Call Logs

Quick Replies

Inbox

Partially update contact CRM

Authentication

Input parameters

Response Fields

​Authentication

​Input parameters

​Response Fields

Authentication

Input parameters

Response Fields