Skip to content
For developers

Clients API

REST endpoints for clients — request and response reference with examples.

Last updated

The people you represent — create, list, update, and remove client records.

Base URL: https://api.actuallycare.com/v1 · Errors use the standard envelope — see Errors.

List all clients#

GET/v1/clients

Returns paginated list of client contacts. Default page size 25 (max 100).

Parameters#

ParameterInTypeRequiredDescription
client_typequeryenumNoOne of: buyer, seller, both
statusqueryenumNoOne of: active, inactive, closed
pagequeryintegerNoPage number for pagination · Default: 1 · Min: 1
limitqueryintegerNoNumber of items per page (default 25, max 100) · Default: 25 · Max: 100 · Min: 1

Responses#

StatusMeaningWhat to do
200Paginated list — records under data.clients, pagination under data.meta
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl "https://api.actuallycare.com/v1/clients" \
  -H "X-API-Key: YOUR_API_KEY"

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

Kept in this browser tab only, and filled into the samples on this page.
GET /v1/clients

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "clients": [
      {
        "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
        "first_name": "Michael",
        "last_name": "Torres",
        "email": "[email protected]",
        "phone": "(661) 555-0142",
        "client_type": "buyer",
        "status": "active",
        "source": "Zillow",
        "budget_min": 350000,
        "budget_max": 475000
      }
    ],
    "meta": {
      "page": 1,
      "limit": 25,
      "total": 42,
      "totalPages": 2,
      "hasMore": true
    }
  }
}

Create new client#

POST/v1/clients

Request body#

FieldTypeRequiredDescription
first_namestringYesClient's first name
last_namestringYesClient's last name
emailstringNoClient's email address
phonestringNoClient's phone number
client_typeenumYesWhether the client is a buyer, seller, or both · One of: buyer, seller, both

Responses#

StatusMeaningWhat to do
201Client created
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X POST "https://api.actuallycare.com/v1/clients" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Lee",
    "client_type": "buyer"
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
    "first_name": "Michael",
    "last_name": "Torres",
    "email": "[email protected]",
    "phone": "(661) 555-0142",
    "client_type": "buyer",
    "status": "active",
    "version": 1,
    "created_at": "2026-07-01T22:49:27.331Z",
    "updated_at": "2026-07-01T22:49:27.331Z"
  }
}

Get client by ID#

GET/v1/clients/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Client found
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl "https://api.actuallycare.com/v1/clients/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

Kept in this browser tab only, and filled into the samples on this page.
GET /v1/clients/

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
    "first_name": "Michael",
    "last_name": "Torres",
    "email": "[email protected]",
    "phone": "(661) 555-0142",
    "client_type": "buyer",
    "status": "active",
    "source": "Zillow",
    "budget_min": 350000,
    "budget_max": 475000,
    "pre_approved": true,
    "pre_approval_amount": 460000,
    "version": 2
  }
}

Update client#

PUT/v1/clients/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
emailstringNoClient's email address
phonestringNoClient's phone number
statusstringNoClient status (active, inactive, closed)
versionintegerNoCurrent record version for optimistic locking

Responses#

StatusMeaningWhat to do
200Client updated
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X PUT "https://api.actuallycare.com/v1/clients/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+1 661 555 0123",
    "status": "your-status",
    "version": 3
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "(555) 123-4567",
    "client_type": "buyer",
    "status": "active",
    "source": "Zillow",
    "budget_min": 400000,
    "budget_max": 650000,
    "preferred_locations": [
      "example preferred locations"
    ],
    "property_preferences": {
      "bedrooms_min": 3,
      "bathrooms_min": 3,
      "square_feet_min": 1800,
      "property_types": [
        "example property types"
      ]
    },
    "pre_approved": true,
    "pre_approval_amount": 450000,
    "notes": "example notes",
    "tags": [
      "example tags"
    ],
    "version": 1,
    "created_at": "2026-07-15T14:32:10.000Z",
    "updated_at": "2026-07-15T14:32:10.000Z"
  }
}

Delete client#

DELETE/v1/clients/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Client deleted
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X DELETE "https://api.actuallycare.com/v1/clients/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {},
  "timestamp": "2026-07-15T14:32:10.000Z"
}