Clients API

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

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#

Parameter	In	Type	Required	Description
`client_type`	query	enum	No	One of: `buyer`, `seller`, `both`
`status`	query	enum	No	One of: `active`, `inactive`, `closed`
`page`	query	integer	No	Page number for pagination · Default: `1` · Min: 1
`limit`	query	integer	No	Number of items per page (default 25; GET /escrows overrides this to 20 at the controller level) · Default: `25` · Max: 100 · Min: 1

Responses#

Status	Meaning
`200`	Paginated list — records under data.clients, pagination under data.meta
`401`	Authentication required
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/clients", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/clients",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()

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#

Field	Type	Required	Description
`first_name`	string	Yes	Client's first name
`last_name`	string	Yes	Client's last name
`email`	string	No	Client's email address
`phone`	string	No	Client's phone number
`client_type`	enum	Yes	Whether the client is a buyer, seller, or both · One of: `buyer`, `seller`, `both`

Responses#

Status	Meaning
`201`	Client created
`400`	Invalid request data
`401`	Authentication required
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

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"
  }'

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/clients", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "first_name": "Jordan",
    "last_name": "Lee",
    "client_type": "buyer"
  }),
});
const data = await res.json();

Python

import requests
 
resp = requests.post(
    "https://api.actuallycare.com/v1/clients",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "first_name": "Jordan",
        "last_name": "Lee",
        "client_type": "buyer"
    },
)
data = resp.json()

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#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier (UUID) · Format: uuid

Responses#

Status	Meaning
`200`	Client found
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/clients/:id", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/clients/:id",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()

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#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier (UUID) · Format: uuid

Request body#

Field	Type	Required	Description
`email`	string	No	Client's email address
`phone`	string	No	Client's phone number
`status`	string	No	Client status (active, inactive, closed)
`version`	integer	No	Current record version for optimistic locking

Responses#

Status	Meaning
`200`	Client updated
`400`	Invalid request data
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

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
  }'

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/clients/:id", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "phone": "+1 661 555 0123",
    "status": "your-status",
    "version": 3
  }),
});
const data = await res.json();

Python

import requests
 
resp = requests.put(
    "https://api.actuallycare.com/v1/clients/:id",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "email": "[email protected]",
        "phone": "+1 661 555 0123",
        "status": "your-status",
        "version": 3
    },
)
data = resp.json()

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#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier (UUID) · Format: uuid

Responses#

Status	Meaning
`200`	Client deleted
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/clients/:id", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.delete(
    "https://api.actuallycare.com/v1/clients/:id",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()

Example response (200)#

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