# Appointments API

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

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

Calendar events — create, list, update, and cancel appointments.

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

## List all appointments

```http
GET /v1/appointments
```

Returns paginated list of appointments/showings. Default page size 25 (max 100).

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `appointment_type` | query | enum | No | One of: `showing`, `inspection`, `signing`, `meeting`, `call`, `other` |
| `status` | query | enum | No | One of: `scheduled`, `completed`, `cancelled`, `no_show` |
| `start_date` | query | string | No | Format: date |
| `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/appointments" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript title="JavaScript"
const res = await fetch("https://api.actuallycare.com/v1/appointments", {
  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/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()
```

### Example response (200)

```json
{
  "success": true,
  "data": {
    "appointments": [
      {
        "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46",
        "title": "Buyer consultation — Torres family",
        "appointment_type": "meeting",
        "start_time": "2026-07-10T17:00:00Z",
        "end_time": "2026-07-10T18:00:00Z",
        "location": "9900 Stockdale Hwy, Bakersfield, CA 93311",
        "client_id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
        "status": "scheduled"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 25,
      "total": 12,
      "totalPages": 1,
      "hasMore": false
    }
  },
  "timestamp": "2026-07-01T22:50:41.207Z"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Paginated list — records under data.appointments, 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 appointment

```http
POST /v1/appointments
```

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes | Appointment title |
| `start_time` | string | Yes | Appointment start time (ISO 8601) · Format: date-time |
| `end_time` | string | Yes | Appointment end time (ISO 8601) · Format: date-time |
| `appointment_type` | string | No | Type of appointment (showing, inspection, signing, meeting, call, other) |
| `location` | string | No | Appointment location |

### Example request

```bash title="cURL"
curl -X POST "https://api.actuallycare.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "your-title",
    "start_time": "your-start-time",
    "end_time": "your-end-time"
  }'
```

```javascript title="JavaScript"
const res = await fetch("https://api.actuallycare.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "your-title",
    "start_time": "your-start-time",
    "end_time": "your-end-time"
  }),
});
const data = await res.json();
```

```python title="Python"
import requests

resp = requests.post(
    "https://api.actuallycare.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "your-title",
        "start_time": "your-start-time",
        "end_time": "your-end-time"
    },
)
data = resp.json()
```

### Example response (201)

```json
{
  "success": true,
  "data": {
    "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46",
    "title": "Showing — 456 Oak Ave",
    "appointment_type": "showing",
    "start_time": "2026-07-12T21:30:00Z",
    "end_time": "2026-07-12T22:00:00Z",
    "location": "456 Oak Ave, Tehachapi, CA 93561",
    "status": "scheduled",
    "version": 1
  },
  "message": "Appointment created successfully",
  "timestamp": "2026-07-01T22:51:12.940Z"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | Appointment 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 appointment by ID

```http
GET /v1/appointments/{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/appointments/:id" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript title="JavaScript"
const res = await fetch("https://api.actuallycare.com/v1/appointments/: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/appointments/:id",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = resp.json()
```

### Example response (200)

```json
{
  "success": true,
  "data": {
    "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46",
    "title": "Buyer consultation — Torres family",
    "appointment_type": "meeting",
    "start_time": "2026-07-10T17:00:00Z",
    "end_time": "2026-07-10T18:00:00Z",
    "location": "9900 Stockdale Hwy, Bakersfield, CA 93311",
    "client_id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684",
    "status": "scheduled",
    "version": 1
  },
  "timestamp": "2026-07-01T22:51:44.518Z"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Appointment 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 appointment

```http
PUT /v1/appointments/{id}
```

### Parameters

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start_time` | string | No | Appointment start time (ISO 8601) · Format: date-time |
| `end_time` | string | No | Appointment end time (ISO 8601) · Format: date-time |
| `status` | string | No | Appointment status (scheduled, completed, cancelled, no_show) |
| `version` | integer | No | Current record version for optimistic locking |

### Example request

```bash title="cURL"
curl -X PUT "https://api.actuallycare.com/v1/appointments/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "your-start-time",
    "end_time": "your-end-time",
    "status": "your-status",
    "version": 3
  }'
```

```javascript title="JavaScript"
const res = await fetch("https://api.actuallycare.com/v1/appointments/:id", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "start_time": "your-start-time",
    "end_time": "your-end-time",
    "status": "your-status",
    "version": 3
  }),
});
const data = await res.json();
```

```python title="Python"
import requests

resp = requests.put(
    "https://api.actuallycare.com/v1/appointments/:id",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "start_time": "your-start-time",
        "end_time": "your-end-time",
        "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",
    "title": "Property Showing - 123 Main St",
    "description": "example description",
    "appointment_type": "showing",
    "start_time": "2025-02-01T14:00:00Z",
    "end_time": "2025-02-01T15:00:00Z",
    "location": "123 Main St, Tehachapi, CA 93561",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "listing_id": "550e8400-e29b-41d4-a716-446655440000",
    "escrow_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "scheduled",
    "attendees": [
      {
        "name": "Jordan Lee",
        "email": "agent@example.com",
        "phone": "+1 661 555 0123"
      }
    ],
    "reminder_sent": true,
    "notes": "example notes",
    "version": 1,
    "created_at": "2026-07-15T14:32:10.000Z",
    "updated_at": "2026-07-15T14:32:10.000Z"
  },
  "timestamp": "2026-07-15T14:32:10.000Z"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Appointment 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 appointment

```http
DELETE /v1/appointments/{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/appointments/:id" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript title="JavaScript"
const res = await fetch("https://api.actuallycare.com/v1/appointments/: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/appointments/: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` | Appointment 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 |