Events V1 — Developer Guide

Reference: Events (V1) Endpoint Documentation

Events represent non-patient schedule blocks on the office calendar — team meetings, training sessions, closures, and similar items. They are distinct from AppointmentV1 records, which are tied to patients and clinical workflows.

All Events V1 endpoints require an Organization-ID header. Read operations require the model:read scope; write operations (POST, PUT, DELETE) require model:write.

⚠️ Rate Limited: Events endpoints are rate limited. See the rate limiting guide for details.

Returns a paginated list of events matching the provided filter criteria.

Upcoming Breaking Change: location.id (as a list of IDs or ["ALL"]) will become a required filter. Omitting it currently defaults to all locations. See Location-Based API Billing.

Date-limiting filter: If you do not provide a date-limiting filter (lastModified, start, or createdDate), the server may automatically apply lastModified >= your organization's creation date or one year ago — whichever is more recent.

Ordering: When filtering by start or lastModified, results are returned in descending order (newest first). Use lastId with date filters for stable pagination.

Fetch events modified after a date at a specific location:

GET /api/v1/events?filter=lastModified>=2025-01-01T00:00:00Z,location.id->[64000000000004]

Fetch events for a provider within a date range:

GET /api/v1/events?filter=start>=2025-06-01,start<=2025-06-30,provider.id==789

Paginate using lastId:

GET /api/v1/events?lastId=9000000903375&pageSize=100&filter=lastModified>=2025-01-01T00:00:00Z,location.id->[64000000000004]

Returns a single event by its ID.

GET /api/v1/events/9000000903375

GET /api/v1/events/async retrieves events asynchronously. It returns the first 10 matching results immediately in the HTTP response and streams all matching records to the Streaming API.

See the Async Endpoints V1 — Developer Guide for shared async mechanics, parameters, and pagination. Filter keys are the same as bulk list above.

Returns the total number of events matching a filter. Uses the same filter syntax as GET /v1/events.

GET /api/v1/events/totalcount?filter=lastModified>=2025-01-01,location.id==123

Creates a new event. Supports one-time and recurring events (WEEKLY or MONTHLY patterns).

Required fields:

Optional fields:

Recurrence fields (all required together when creating a recurring series):

POST /api/v1/events
Content-Type: application/json

{
  "title": "Team Meeting",
  "start": "2025-01-15T10:00:00.000Z",
  "duration": 60,
  "location": { "id": "64000000000004" },
  "operatory": { "id": "9000000000338" },
  "color": "FF5733"
}

POST /api/v1/events
Content-Type: application/json

{
  "title": "Weekly Standup",
  "start": "2025-01-15T10:00:00.000Z",
  "duration": 30,
  "location": { "id": "64000000000004" },
  "recurrenceType": "WEEKLY",
  "recurrenceStart": "2025-01-15",
  "recurrenceEnd": "2025-06-15",
  "recurrenceFrequency": 1,
  "recurrenceDays": ["MONDAY", "WEDNESDAY", "FRIDAY"]
}

Returns 201 Created with the created EventV1 in data.

Updates an existing event. The request body uses the EventV1 model with partial update semantics: only properties present in the JSON body are changed; omitted properties are left unchanged.

Note: Although the EventV1 schema lists title, start, and location as required for create, none of these are required on PUT. Send only the fields you want to change.

PUT /api/v1/events/9000000903375?recurrenceTarget=OCCURRENCE
Content-Type: application/json

{
  "title": "Updated Team Meeting",
  "duration": 90
}

Returns 200 OK with the updated EventV1 in data.

Deletes an event by ID.

Delete a one-time event:

DELETE /api/v1/events/9000000903375

Delete a single occurrence from a recurring series:

DELETE /api/v1/events/9000000903375?recurrenceTarget=OCCURRENCE

Returns 200 OK with { "data": { "id": <eventId> } }.

A successful response returns the following top-level structure:

For bulk responses, data is an array and the response also includes meta.pagination with lastId for cursor pagination.

lastId is the recommended approach for iterating through large result sets. It uses the event's id as a cursor rather than an offset.

GET /api/v1/events?pageSize=100&filter=lastModified>=2025-01-01T00:00:00Z,location.id->[64000000000004]

Pass the id of the last record in data as lastId:

GET /api/v1/events?lastId=9000000903375&pageSize=100&filter=lastModified>=2025-01-01T00:00:00Z,location.id->[64000000000004]

Continue until data is empty.

⚠️ Not Recommended: Do not paginate large data sets using the page parameter. Use lastId instead.

Events are streamable via the Streaming API. Create, update, and delete operations emit stream messages. The async bulk GET endpoint also delivers matching records to the Streaming API.

See the Streaming API Webhooks Setup Guide for setup instructions.

organizationId.locationId.EventV1.operationType

All event changes at a specific location:

66d22762060811049b50d085.64000000000004.EventV1.*

All CREATE events across all locations:

66d22762060811049b50d085.*.EventV1.CREATE