Overview
The Owners API (also called Pet Owners or Clients) allows you to manage client records, track engagement, and organize customer relationships.
The Owner Object
Unique identifier for the owner
Emergency contact phone number
Preferred contact method: phone, email, sms
How the client was acquired: AI Call, Walk-in, Website, Referral
Client status: New Client, Contacted, Appointment Booked, Regular Client, Churned
Engagement score (0-100) based on activity
ID of the assigned primary veterinarian
Client’s preferred veterinarian
Internal notes about the client
Array of pet IDs belonging to this owner
Date of last visit (YYYY-MM-DD)
Timestamp of last contact
When the record was created
When the record was last updated
List All Owners
curl -X GET http://localhost:3000/api/owners \
-H "Authorization: Bearer $TOKEN"
Query Parameters
Filter by acquisition source
Search by name, email, or phone
Response
[
{
"id": "owner-123",
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"phone": "+1-555-0123",
"address": "123 Main St, San Francisco, CA 94102",
"emergencyContactName": "Jane Smith",
"emergencyContactPhone": "+1-555-0124",
"preferredContact": "email",
"source": "Website",
"status": "Regular Client",
"engagementScore": 85,
"assignedVetId": "vet-001",
"preferredVetId": "vet-001",
"notes": "Prefers morning appointments",
"pets": ["pet-001", "pet-002"],
"lastVisit": "2024-12-10",
"lastContactAt": "2024-12-15T09:30:00Z",
"createdAt": "2023-06-15T14:20:00Z",
"updatedAt": "2024-12-15T09:30:00Z"
}
]
Get Owner by ID
curl -X GET http://localhost:3000/api/owners/owner-123 \
-H "Authorization: Bearer $TOKEN"
Path Parameters
Create Owner
curl -X POST http://localhost:3000/api/owners \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Emily",
"lastName": "Johnson",
"email": "[email protected]",
"phone": "+1-555-0199",
"preferredContact": "sms",
"source": "AI Call",
"status": "New Client"
}'
Request Body
status
string
default:"New Client"
Client status
Update Owner
curl -X PATCH http://localhost:3000/api/owners/owner-123 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "Regular Client",
"engagementScore": 90,
"lastContactAt": "2024-12-16T10:00:00Z"
}'
Path Parameters
Delete Owner
Deleting an owner will not delete their pets. Consider setting status to “Churned” instead.
curl -X DELETE http://localhost:3000/api/owners/owner-123 \
-H "Authorization: Bearer $TOKEN"
Client Engagement Tracking
Track client engagement automatically:
// Engagement score increases with:
// - Appointment completion (+10)
// - Timely arrivals (+5)
// - Follow-up compliance (+15)
// - Referrals (+20)
// - Review submission (+10)
const owner = await ownersApi.getById('owner-123');
if (owner.engagementScore > 80) {
console.log('High-value client');
}
Example: Client Lifecycle
import { ownersApi, petsApi } from '@/lib/api';
// 1. Client calls, AI creates record
const newClient = await ownersApi.create({
firstName: 'Sarah',
lastName: 'Williams',
email: '[email protected]',
phone: '+1-555-0167',
source: 'AI Call',
status: 'New Client',
preferredContact: 'phone'
});
// 2. Add their pet
const pet = await petsApi.create({
ownerId: newClient.id,
name: 'Max',
species: 'dog',
breed: 'Labrador',
gender: 'male',
age: 3
});
// 3. Update status after booking
await ownersApi.update(newClient.id, {
status: 'Appointment Booked',
pets: [pet.id]
});
// 4. After successful visit
await ownersApi.update(newClient.id, {
status: 'Regular Client',
engagementScore: 60,
lastVisit: new Date().toISOString().split('T')[0],
lastContactAt: new Date().toISOString()
});