Appointments API

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

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

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

List all appointments#

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

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

Example request#

cURL

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

JavaScript

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

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

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

Create new appointment#

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

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

Example request#

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

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

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

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

Get appointment by ID#

GET/v1/appointments/{id}

Parameters#

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

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

Example request#

cURL

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

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

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

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

Update appointment#

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

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

Example request#

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

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

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

{
  "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": "[email protected]",
        "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"
}

Delete appointment#

DELETE/v1/appointments/{id}

Parameters#

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

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

Example request#

cURL

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

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

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

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