# Clients API

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

<!-- Source: https://docs.actuallycare.com/api/reference/clients -->

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

Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors).

## List all clients

```http
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 |

### Example request

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

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

```python title="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)

```json
{
  "success": true,
  "data": {
    "clients": [
      {
        "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
        "first_name": "Michael",
        "last_name": "Torres",
        "email": "michael.torres@gmail.com",
        "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
    }
  }
}
```

### 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 |

## Create new client

```http
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` |

### Example request

```bash title="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 title="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 title="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)

```json
{
  "success": true,
  "data": {
    "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
    "first_name": "Michael",
    "last_name": "Torres",
    "email": "michael.torres@gmail.com",
    "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"
  }
}
```

### 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 |

## Get client by ID

```http
GET /v1/clients/{id}
```

### Parameters

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

### Example request

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

```javascript title="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 title="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)

```json
{
  "success": true,
  "data": {
    "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
    "first_name": "Michael",
    "last_name": "Torres",
    "email": "michael.torres@gmail.com",
    "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
  }
}
```

### 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 |

## Update client

```http
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 |

### Example request

```bash title="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": "agent@example.com",
    "phone": "+1 661 555 0123",
    "status": "your-status",
    "version": 3
  }'
```

```javascript title="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": "agent@example.com",
    "phone": "+1 661 555 0123",
    "status": "your-status",
    "version": 3
  }),
});
const data = await res.json();
```

```python title="Python"
import requests

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

### Example response (200)

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "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"
  }
}
```

### 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 |

## Delete client

```http
DELETE /v1/clients/{id}
```

### Parameters

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

### Example request

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

```javascript title="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 title="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)

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

### 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 |