Skip to content
For developers

Appointments API

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

Last updated

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#

ParameterInTypeRequiredDescription
appointment_typequeryenumNoOne of: showing, inspection, signing, meeting, call, other
statusqueryenumNoOne of: scheduled, completed, cancelled, no_show
start_datequerystringNoFormat: date
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.appointments, 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/appointments" \
  -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/appointments

Enter your API key to send.

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#

FieldTypeRequiredDescription
titlestringYesAppointment title
start_timestringYesAppointment start time (ISO 8601) · Format: date-time
end_timestringYesAppointment end time (ISO 8601) · Format: date-time
appointment_typestringNoType of appointment (showing, inspection, signing, meeting, call, other)
locationstringNoAppointment location

Responses#

StatusMeaningWhat to do
201Appointment 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/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"
  }'

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Appointment 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/appointments/: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/appointments/

Enter your API key to send.

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
start_timestringNoAppointment start time (ISO 8601) · Format: date-time
end_timestringNoAppointment end time (ISO 8601) · Format: date-time
statusstringNoAppointment status (scheduled, completed, cancelled, no_show)
versionintegerNoCurrent record version for optimistic locking

Responses#

StatusMeaningWhat to do
200Appointment 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/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
  }'

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Appointment 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/appointments/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

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