Contacts API
REST endpoints for contacts — request and response reference with examples.
Last updated
Your wider address book — vendors, lenders, other agents, and everyone else in your sphere.
Base URL: https://api.actuallycare.com/v1 · Errors use the standard envelope — see Errors.
List contacts#
Returns a paginated list of contacts visible to the authenticated user, with aggregate stats by status. Supports fuzzy search across name and email.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
search | query | string | No | Fuzzy search across full name, first name, last name, and email |
type | query | string | No | Filter by contact type |
archived | query | boolean | No | Show archived contacts instead of active ones · Default: false |
page | query | integer | No | Page number for pagination · Default: 1 · Min: 1 |
limit | query | integer | No | Number of items per page (default 25, max 100) · Default: 25 · Max: 100 · Min: 1 |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Paginated contact list with stats | |
400 | Invalid request data | Fix the request; error.message and error.details name the problem. Don't retry unchanged |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl "https://api.actuallycare.com/v1/contacts" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts", {
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.get(
"https://api.actuallycare.com/v1/contacts",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Try it
Sends a real request from your browser to the API, as you. GET requests only read data.
GET /v1/contactsEnter your API key to send.
Example response (200)#
{
"success": true,
"data": {
"contacts": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
],
"stats": {},
"meta": {
"total": 150,
"page": 1,
"limit": 20,
"totalPages": 8,
"hasMore": true
}
}
}Create a contact#
Adds a contact to the authenticated user's database. First name and contact type are required.
Request body#
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string | Yes | Contact's first name |
last_name | string | No | Contact's last name |
contact_type | enum | Yes | Role this contact plays in transactions (e.g. buyer, seller, lender, inspector) · One of: buyer, seller, agent, lender, title_officer, inspector, appraiser, contractor, client, vendor, other |
email | string | No | Contact's email address · Format: email |
phone | string | No | Contact's phone number |
company | string | No | Company or organization the contact belongs to |
license_number | string | No | Professional license number (e.g. for agents, lenders, inspectors) |
street_address | string | No | Street address |
city | string | No | City name |
state | string | No | Two-letter state code |
zip_code | string | No | ZIP code |
notes | string | No | Free-form notes about the contact |
tags | array of strings | No | Free-form labels for grouping and filtering contacts |
Responses#
| Status | Meaning | What to do |
|---|---|---|
201 | Contact created | |
400 | Invalid request data | Fix the request; error.message and error.details name the problem. Don't retry unchanged |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X POST "https://api.actuallycare.com/v1/contacts" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jordan",
"contact_type": "buyer"
}'const res = await fetch("https://api.actuallycare.com/v1/contacts", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"first_name": "Jordan",
"contact_type": "buyer"
}),
});
const data = await res.json();import requests
resp = requests.post(
"https://api.actuallycare.com/v1/contacts",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"first_name": "Jordan",
"contact_type": "buyer"
},
)
data = resp.json()Example response (201)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Search contacts#
Searches the authenticated user's contacts by name, email, or role. Returns a flat array (not paginated) capped at the requested limit.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
name | query | string | No | Case-insensitive substring match on full name |
email | query | string | No | Case-insensitive substring match on email |
role | query | string | No | Filter by assigned contact role name |
limit | query | integer | No | Default: 50 · Max: 100 · Min: 1 |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Matching contacts | |
400 | Invalid request data | Fix the request; error.message and error.details name the problem. Don't retry unchanged |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl "https://api.actuallycare.com/v1/contacts/search" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/search", {
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.get(
"https://api.actuallycare.com/v1/contacts/search",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Try it
Sends a real request from your browser to the API, as you. GET requests only read data.
GET /v1/contacts/searchEnter your API key to send.
Example response (200)#
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
],
"count": 3
}Get a contact#
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier (UUID) · Format: uuid |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | The contact | |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
404 | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl "https://api.actuallycare.com/v1/contacts/:id" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", {
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.get(
"https://api.actuallycare.com/v1/contacts/:id",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Try it
Sends a real request from your browser to the API, as you. GET requests only read data.
GET /v1/contacts/Enter your API key to send.
Example response (200)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Update a contact#
Updates contact fields. All fields are optional; only the fields you send are changed.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier (UUID) · Format: uuid |
Request body#
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string | No | Contact's first name |
last_name | string | No | Contact's last name |
email | string | No | Contact's email address · Format: email |
phone | string | No | Contact's phone number |
contact_type | string | No | Role this contact plays in transactions (e.g. buyer, seller, lender, inspector) |
contact_status | string | No | Workflow status of the contact (free-form, e.g. active, lead, client, past_client) |
company | string | No | Company or organization the contact belongs to |
street_address | string | No | Street address |
city | string | No | City name |
state | string | No | Two-letter state code |
zip_code | string | No | ZIP code |
notes | string | No | Free-form notes about the contact |
tags | array of strings | No | Free-form labels for grouping and filtering contacts |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Contact updated | |
400 | Invalid request data | Fix the request; error.message and error.details name the problem. Don't retry unchanged |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
404 | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X PUT "https://api.actuallycare.com/v1/contacts/:id" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jordan",
"last_name": "Lee",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "your-contact-type",
"contact_status": "your-contact-status",
"company": "your-company",
"street_address": "your-street-address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "your-notes",
"tags": [
"your-tags"
]
}'const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", {
method: "PUT",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"first_name": "Jordan",
"last_name": "Lee",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "your-contact-type",
"contact_status": "your-contact-status",
"company": "your-company",
"street_address": "your-street-address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "your-notes",
"tags": [
"your-tags"
]
}),
});
const data = await res.json();import requests
resp = requests.put(
"https://api.actuallycare.com/v1/contacts/:id",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"first_name": "Jordan",
"last_name": "Lee",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "your-contact-type",
"contact_status": "your-contact-status",
"company": "your-company",
"street_address": "your-street-address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "your-notes",
"tags": [
"your-tags"
]
},
)
data = resp.json()Example response (200)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Delete a contact#
Soft-deletes a contact. Deleted contacts disappear from all lists and searches and cannot be restored; to hide a contact reversibly, use archive instead.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier (UUID) · Format: uuid |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Contact deleted (response echoes the deleted contact record) | |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
403 | Caller lacks permission to delete this contact | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors |
404 | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X DELETE "https://api.actuallycare.com/v1/contacts/:id" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", {
method: "DELETE",
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.delete(
"https://api.actuallycare.com/v1/contacts/:id",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Example response (200)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Archive a contact#
Hides a contact from default lists. Archived contacts can be listed with archived=true and restored at any time.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier (UUID) · Format: uuid |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Contact archived (response is the updated contact record) | |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
404 | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X PATCH "https://api.actuallycare.com/v1/contacts/:id/archive" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/:id/archive", {
method: "PATCH",
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.patch(
"https://api.actuallycare.com/v1/contacts/:id/archive",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Example response (200)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Restore an archived contact#
Returns an archived contact to the active list.
Parameters#
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier (UUID) · Format: uuid |
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Contact restored (response is the updated contact record) | |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
404 | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X PATCH "https://api.actuallycare.com/v1/contacts/:id/restore" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/:id/restore", {
method: "PATCH",
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.patch(
"https://api.actuallycare.com/v1/contacts/:id/restore",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Example response (200)#
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"first_name": "Jordan",
"last_name": "Lee",
"full_name": "example full name",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"contact_type": "buyer",
"contact_status": "example contact status",
"company": "example company",
"license_number": "example license number",
"street_address": "example street address",
"city": "Bakersfield",
"state": "CA",
"zip_code": "93301",
"notes": "example notes",
"tags": [
"example tags"
],
"is_archived": false,
"archived_at": "2026-07-15T14:32:10.000Z",
"created_at": "2026-07-15T14:32:10.000Z",
"updated_at": "2026-07-15T14:32:10.000Z"
}
}Extract contact fields from a business-card photo#
Sends the image to Claude and returns structured fields for the agent to review. Does NOT create a contact — the caller decides what to save, so an OCR misread never lands in the CRM unreviewed. Gated by the brokerage AI toggle + agent disclosure acceptance (requireAiEnabled).
Responses#
| Status | Meaning | What to do |
|---|---|---|
200 | Fields extracted from the card, for the agent to review | |
400 | Upload rejected before the image was read — over the 5MB limit, or a MIME type outside the allowlist. Returned directly by the route's multer error handler, which is why this is a 400 and the content-level failures below are 422. | Fix the request; error.message and error.details name the problem. Don't retry unchanged |
401 | Authentication required | Check the X-API-Key header (or bearer token). See Authentication |
403 | AI is disabled for this brokerage, or the agent has not accepted the AI disclosure | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors |
422 | Invalid request data | Fix the value error.message names. Don't retry unchanged |
429 | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after Retry-After. See Rate limits |
500 | Internal server error | Retry with exponential backoff. See Errors |
Example request#
curl -X POST "https://api.actuallycare.com/v1/contacts/scan-card" \
-H "X-API-Key: YOUR_API_KEY"const res = await fetch("https://api.actuallycare.com/v1/contacts/scan-card", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
},
});
const data = await res.json();import requests
resp = requests.post(
"https://api.actuallycare.com/v1/contacts/scan-card",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()Example response (200)#
{
"success": true,
"data": {
"isBusinessCard": true,
"firstName": "example firstName",
"lastName": "example lastName",
"company": "example company",
"jobTitle": "example jobTitle",
"email": "[email protected]",
"phone": "+1 661 555 0123",
"mobile": "example mobile",
"website": "example website",
"addressLine": "example addressLine",
"city": "Bakersfield",
"state": "CA",
"postalCode": "example postalCode",
"licenseNumber": "example licenseNumber",
"confidence": "high",
"model": "example model",
"usage": {}
}
}