List appointments (date range)

list appointments in a date range.

GET https://api.centerfy.ai/webhooks/inbound/appointments

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or Authorization: Bearer `<key>`.

Query parameters

Name	Type	Required	Default	Description
`from`	`string`	Yes		Start of the range, ISO 8601. Include a UTC offset/Z or pass `timezone`. Must be on or before `to`. Invalid → 400.
`to`	`string`	Yes		End of the range, ISO 8601. A date-only `to` (e.g. 2026-06-20, no time component) is treated as inclusive of the whole day (extended to 23:59:59.999). Invalid → 400.
`timezone`	`string`	No		IANA timezone used to interpret bare (offset-less) from/to values.
`status`	`string`	No		Optional filter; one of: scheduled, confirmed, completed, cancelled, no_show (case-insensitive). Other values → 400.
`limit`	`string`	No	`100`	Maximum rows to return; positive integer, capped at 500. Non-integer or <= 0 → 400.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/appointments?from=&to=&timezone=" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.appointments.list({
  "from": 0,
  "to": 0,
  "timezone": 0,
  "status": 0,
  "limit": 100
});
console.log(result);

centerfy appointments list '{"from":0,"to":0,"timezone":0,"status":0,"limit":100}'

MCP tool: centerfy_appointments_list (see MCP server)

Response

{
  "status": "success",
  "from": "2026-06-20T00:00:00.000Z",
  "to": "2026-06-20T23:59:59.999Z",
  "appointment_count": 1,
  "appointments": [
    {
      "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
      "title": "Discovery Call",
      "description": "Intro call to discuss requirements",
      "appointment_date": "2026-06-20T15:00:00.000Z",
      "duration_minutes": 30,
      "location": "Zoom",
      "notes": null,
      "status": "scheduled",
      "contact_id": "f1e2d3c4-b5a6-4978-8c9d-0e1f2a3b4c5d",
      "contact": {
        "id": "f1e2d3c4-b5a6-4978-8c9d-0e1f2a3b4c5d",
        "name": "Jane Doe",
        "email": "[email protected]",
        "phone": "+15551234567"
      },
      "calendar_id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
      "created_at": "2026-06-12T09:00:00.000Z",
      "updated_at": "2026-06-12T09:00:00.000Z"
    }
  ]
}

Errors

400 — if from or to is missing or invalid, from is after to, status is invalid, or limit is invalid.
500 — on an internal error.

Notes

Lists appointments whose appointment_date falls within [from, to], ordered by appointment_date ascending. Both from and to are required. Each appointment includes its linked contact (null if none). The normalized from/to values are echoed in the response. Undeclared query params are ignored.