Appointments

List appointments

GET /v1/appointments

Scope

appointments:read

Tier

Tier 1

Data

Personal data

Idempotency

Idempotency-Key: not used

Limit

Up to 100 per page (default 50)

Soonest first. scheduled_from and scheduled_to bound the appointment time; the range is at most 92 days (default: the next 30 days).

Parameters

Response

200: One page of appointments.

Examples

Request example

curl

curl -sS -X GET \
  "https://app.dialerbee.com/api/v1/appointments?limit=50" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY"

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

page = db.appointments.list(limit=50)
for item in page:  # this page, then every following page
    print(item.id)

Response example

200

{
  "data": [
    {
      "id": "appt_0f8fad5b-d9cb-469f-a165-70867728950e",
      "status": "confirmed",
      "scheduled_at": "2026-10-01T14:00:00Z",
      "timezone": "Asia/Amman",
      "duration_minutes": 30,
      "service_type": "Consultation",
      "contact_name": "Ann Lee",
      "phone": "+12125550101",
      "email": "[email protected]",
      "notes": "Prefers calls after 5 pm.",
      "source": "api",
      "created_at": "2026-09-29T09:15:00Z",
      "updated_at": "2026-09-29T09:20:00Z"
    }
  ],
  "page": {
    "next_cursor": "c1.example-opaque-cursor",
    "has_more": true
  }
}

Error examples

400 invalid_cursor

{
  "type": "https://docs.dialerbee.com/errors/invalid-cursor",
  "title": "Invalid cursor",
  "status": 400,
  "detail": "The cursor is not valid for this request: it was changed, it belongs to another list or other filters, or it expired.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "invalid_cursor",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

400 invalid_date_range

{
  "type": "https://docs.dialerbee.com/errors/invalid-date-range",
  "title": "Invalid date range",
  "status": 400,
  "detail": "The date range is empty, reversed or longer than the maximum the operation allows (92 days).",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "invalid_date_range",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

403 insufficient_scope

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

AppointmentList

Page

Pass next_cursor as cursor to get the next page. null means this is the last page.

Appointment