Appointments

List Appointments

GET /api/v1/appointments

Scope: appointments:read

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Results per page (1-100)
`status`	string	—	Filter: `scheduled`, `confirmed`, `completed`, `cancelled`, `no_show`
`lead_id`	UUID	—	Filter by lead
`start_after`	ISO 8601	—	Appointments starting after this time
`start_before`	ISO 8601	—	Appointments starting before this time
`sort_by`	string	`start_time`	Sort: `start_time` or `created_at`
`sort_dir`	string	`desc`	Direction: `asc` or `desc`

Example

curl "https://api.brightlyai.app/api/v1/appointments?status=scheduled&limit=10" \
  -H "Authorization: Bearer brk_your_key"

Response

{
  "data": [
    {
      "id": "b2c3d4e5-...",
      "organization_id": "org-uuid-...",
      "lead_id": "a1b2c3d4-...",
      "start_time": "2026-05-15T10:00:00Z",
      "end_time": "2026-05-15T11:00:00Z",
      "status": "scheduled",
      "type": "Estimate",
      "location": "123 Main St, Austin TX",
      "notes": "Roof inspection for hail damage",
      "booked_by": "api",
      "outcome": null,
      "outcome_notes": null,
      "created_at": "2026-05-10T14:30:00Z",
      "updated_at": "2026-05-10T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 23,
    "total_pages": 3
  }
}

Get Appointment

GET /api/v1/appointments/:id

Scope: appointments:read

curl "https://api.brightlyai.app/api/v1/appointments/b2c3d4e5-..." \
  -H "Authorization: Bearer brk_your_key"

Create Appointment

POST /api/v1/appointments

Scope: appointments:write

Request Body

Field	Type	Required	Description
`lead_id`	UUID	Yes	The lead this appointment is for. Must exist in your org.
`start_time`	ISO 8601	Yes	Appointment start time
`end_time`	ISO 8601	Yes	Appointment end time
`type`	string	No	Appointment type (max 100 chars). e.g. “Estimate”, “Installation”
`location`	string	No	Location (max 500 chars)
`notes`	string	No	Notes (max 5000 chars)
`status`	string	No	Default: `scheduled`. Options: `scheduled`, `confirmed`, `completed`, `cancelled`, `no_show`

Example

curl -X POST "https://api.brightlyai.app/api/v1/appointments" \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "start_time": "2026-05-15T10:00:00Z",
    "end_time": "2026-05-15T11:00:00Z",
    "type": "Estimate",
    "location": "123 Main St, Austin TX"
  }'

Update Appointment

PUT /api/v1/appointments/:id

Scope: appointments:write

All create fields except lead_id are accepted, all optional. Only provided fields are updated.

curl -X PUT "https://api.brightlyai.app/api/v1/appointments/b2c3d4e5-..." \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed"}'

Cancel Appointment

DELETE /api/v1/appointments/:id

Scope: appointments:write

{
  "data": {
    "id": "b2c3d4e5-...",
    "cancelled": true
  }
}