Events and visits
Events and visits in the BlueSuite REST API
Manage appointments, tasks, and calendar events. Input dates/times use the workspace timezone and are converted to UTC for storage. Times returned from saved events may therefore differ from the local input.
Scheduling rules
Both start_time and end_time are required unless all_day: true. The end must be after the start. For date-only work, explicitly use all_day: true. Flexible visits can use is_flexible and duration_minutes.
Standalone tasks and calendar events can repeat. Appointments repeat through recurring job schedules, rather than standalone appointment recurrence. A custom weekly/monthly pattern requires selected days, and a finite repeat duration requires a count. Only send repeat_frequency_schedule when repeat_frequency_unit is custom.
On updates, update_scope controls which occurrences change. Partial time edits are merged with the existing schedule before validation. Use the dedicated status endpoint for completion/cancellation and PUT /events/:id/line-items to replace a visit's line items; this is a complete replacement of that visit's pricing list.
Example: create a timed appointment
curl 'https://my.bluesuite.app/api/v1/events' \
-H "Authorization: Bearer $BLUESUITE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Site inspection","job_id":42,"type":"appointment","start_date":"2026-11-02","end_date":"2026-11-02","start_time":"09:00","end_time":"10:00"}'GET /api/v1/events
GET /api/v1/eventsRequired scopes: events:read.
Query parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
page | integer | No | Page number, starting at 1. Default: 1. |
per_page | integer | No | Records per page, from 1 to 100. Default: 25. minimum: 1. maximum: 100. |
search | string | No | Search text. maxLength: 100. |
sort_by | string | No | Sort column. See the supported columns below when listed. |
sort_direction | "asc", "desc" | No | Sort direction. Default: "desc". |
start_date | string | No | Inclusive start date, YYYY-MM-DD. |
end_date | string | No | Inclusive end date, YYYY-MM-DD. |
job_id | string | No | Filter by job ID. |
type | string | No | Filter by type. |
assignee_ids | string | No | Comma-separated user UUIDs. |
status | string | No | Filter by status. |
request_id | string | No | Filter by request ID. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/events
POST /api/v1/eventsRequired scopes: events:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
name | string or null | No | |
description | string or null | No | |
job_id | integer or null | No | |
request_id | integer or null | No | |
start_date | string | Yes | |
end_date | string | Yes | |
start_time | string or null | No | |
end_time | string or null | No | |
all_day | boolean | No | Default: false. |
multi_day | boolean | No | Default: false. |
is_flexible | boolean or null | No | |
duration_minutes | integer or null | No | |
type | "appointment", "task", "event" | No | Default: "event". |
status | "scheduled", "cancelled", "missed", "completed" | No | Default: "scheduled". |
assignee_ids | array of string | No | |
recurrence_type | "single", "recurring" | No | Default: "single". |
repeat_frequency | integer or null | No | |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_schedule | object or null | No | |
repeat_frequency_schedule.days | array of integer | When parent supplied | |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | integer or null | No | |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "forever". |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
201 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
GET /api/v1/events/:id
GET /api/v1/events/:idRequired scopes: events:read.
Path parameters: id. Use positive integer record IDs from this workspace.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/events/:id
PUT /api/v1/events/:idRequired scopes: events:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
name | string or null | No | |
description | string or null | No | |
job_id | integer or null | No | |
request_id | integer or null | No | |
start_date | string | No | |
end_date | string | No | |
start_time | string or null | No | |
end_time | string or null | No | |
all_day | boolean | No | Default: false. |
multi_day | boolean | No | Default: false. |
is_flexible | boolean or null | No | |
duration_minutes | integer or null | No | |
type | "appointment", "task", "event" | No | Default: "event". |
status | "scheduled", "cancelled", "missed", "completed" | No | Default: "scheduled". |
assignee_ids | array of string | No | |
recurrence_type | "single", "recurring" | No | Default: "single". |
repeat_frequency | integer or null | No | |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_schedule | object or null | No | |
repeat_frequency_schedule.days | array of integer | When parent supplied | |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | integer or null | No | |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "forever". |
update_scope | "single", "all", "recreate" | No |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
DELETE /api/v1/events/:id
DELETE /api/v1/events/:idRequired scopes: events:write.
Path parameters: id. Use positive integer record IDs from this workspace.
No request body.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/events/:id/line-items
PUT /api/v1/events/:id/line-itemsRequired scopes: events:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
line_items | JSON value or array of object or object or null | No |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/events/:id/status
PUT /api/v1/events/:id/statusRequired scopes: events:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
status | "scheduled", "cancelled", "missed", "completed" | Yes |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.