Contacts
Get contact activities
Retrieve chronological activity timeline for a contact
GET
/
api
/
v1
/
contacts
/
{contact_id}
/
activities
curl -X GET "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10" \
-H "Authorization: Bearer <token>"
import requests
url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities"
params = {
"limit": 10
}
headers = {
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())
const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10", {
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/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10"))
.header("Authorization", "Bearer <token>")
.GET()
.build();
HttpResponse<String> response =
HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
{
"activities": [
{
"id": "c71a39f4-2f22-4217-b715-cf9ec6a0cf55",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "stage_changed",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"old_stage": "engaged",
"new_stage": "qualified"
},
"created_at": "2026-10-07T16:00:00Z"
},
{
"id": "d9818e6b-67e3-4632-9cb4-221272718e88",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "note_added",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"note": "Customer showed interest in multi-seat annual plan."
},
"created_at": "2026-10-07T15:30:00Z"
}
],
"total": 2,
"limit": 10,
"offset": 0,
"has_more": false
}
{
"detail": "Contact not found"
}
{
"detail": "Unauthorized"
}
Retrieve a chronological, paginated activity timeline for a contact (newest first). The timeline tracks all interactions, system events, manual agent notes, campaign messages, lifecycle stage changes, and AI/human handoffs.
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>.integer
default:"50"
Maximum number of activities to return (minimum 1, maximum 100).
integer
default:"0"
Number of activities to skip for pagination.
string[]
Optional filter by one or more activity types (e.g.
note_added, stage_changed, lead_score_changed, handoff_to_human, handoff_to_ai, task_created, task_completed, message_inbound, message_outbound).Response Fields
ActivityResponse[]
List of chronological activity records:
Show Activity record fields
Show Activity record fields
string
Unique UUID identifier of the activity.
string
Organization UUID.
string
Associated contact UUID.
string
Activity type event string (e.g.
contact_created, note_added, stage_changed, lead_score_changed, handoff_to_human, handoff_to_ai, task_created, task_completed).string
Initiator type:
user, ai, or system.string
UUID of the user or agent actor, or
null.object
Event metadata dictionary containing details (such as previous stage, new stage, note text, task ID, etc.).
string
ISO 8601 creation timestamp.
integer
Total count of activities matching filters.
integer
Limit requested.
integer
Pagination offset applied.
boolean
Flag indicating if more activities exist beyond this page.
curl -X GET "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10" \
-H "Authorization: Bearer <token>"
import requests
url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities"
params = {
"limit": 10
}
headers = {
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())
const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10", {
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/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10"))
.header("Authorization", "Bearer <token>")
.GET()
.build();
HttpResponse<String> response =
HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
{
"activities": [
{
"id": "c71a39f4-2f22-4217-b715-cf9ec6a0cf55",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "stage_changed",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"old_stage": "engaged",
"new_stage": "qualified"
},
"created_at": "2026-10-07T16:00:00Z"
},
{
"id": "d9818e6b-67e3-4632-9cb4-221272718e88",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "note_added",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"note": "Customer showed interest in multi-seat annual plan."
},
"created_at": "2026-10-07T15:30:00Z"
}
],
"total": 2,
"limit": 10,
"offset": 0,
"has_more": false
}
{
"detail": "Contact not found"
}
{
"detail": "Unauthorized"
}
‹ PreviousNext ›
Create contact activity
POST /api/v1/contacts/{contact_id}/activities
Was this page helpful?
⌘I
curl -X GET "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10" \
-H "Authorization: Bearer <token>"
import requests
url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities"
params = {
"limit": 10
}
headers = {
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())
const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10", {
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/7b8f9e2a-4c1d-48ef-9123-bcde456789ab/activities?limit=10"))
.header("Authorization", "Bearer <token>")
.GET()
.build();
HttpResponse<String> response =
HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
{
"activities": [
{
"id": "c71a39f4-2f22-4217-b715-cf9ec6a0cf55",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "stage_changed",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"old_stage": "engaged",
"new_stage": "qualified"
},
"created_at": "2026-10-07T16:00:00Z"
},
{
"id": "d9818e6b-67e3-4632-9cb4-221272718e88",
"organization_id": "00000000-0000-0000-0000-000000000001",
"contact_id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
"type": "note_added",
"actor_type": "user",
"actor_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"payload": {
"note": "Customer showed interest in multi-seat annual plan."
},
"created_at": "2026-10-07T15:30:00Z"
}
],
"total": 2,
"limit": 10,
"offset": 0,
"has_more": false
}
{
"detail": "Contact not found"
}
{
"detail": "Unauthorized"
}