Events

An event is something an individual is expected to attend or act on: a court date, a hearing, an appointment, or a deadline. Creating an event schedules reminder messages for the attached client through the event's flow, so the person is notified ahead of the date.

This page assumes the shared API Conventions for pagination, filtering, lifecycle actions, and references. All endpoints use your region's base URL and a Bearer token.

Endpoints

Method	Path	Description
GET	/v1/events	List events
GET	/v1/events/total	Count events matching filters
GET	/v1/events/{uuid}	Get a single event (by UUID or event_reference)
GET	/v1/events/{uuid}/attached	List an event's client attachment records
POST	/v1/events	Create an event
PATCH	/v1/events/{uuid}	Update an event
PUT	/v1/events/{uuid}	Update an event (alias of PATCH)
POST	/v1/events/{uuid}/attach	Attach an additional client to an event
DELETE	/v1/events/{uuid}/detach	Detach a client from an event
POST	/v1/events/{uuid}/process	Reprocess an event (reschedule reminders)
POST	/v1/events/{uuid}/sync	Reprocess an event (behaves identically to process)
PUT	/v1/events/{uuid}/archive	Archive an event
PUT	/v1/events/{uuid}/restore	Restore an archived or deleted event
DELETE	/v1/events/{uuid}	Delete an event (soft delete)

The Event Object

Field	Type	Description
uuid	string	Unique identifier, generated when the event is created.
client	string	UUID of the client the event is for. Reminders are sent to this client's contacts.
event_reference	string	Your identifier for the event, such as a docket or calendar entry ID.
date	string	Event date (YYYY-MM-DD). Required on create.
time	string	Event time (HH:MM, 24-hour).
end_date	string	End date for multi-day events (YYYY-MM-DD).
end_time	string	End time (HH:MM).
type	string	Agency-defined event type, such as hearing or arraignment.
status	string	Agency-defined status.
appeared	string	Appearance outcome, set after the event.
case_number	string	Case number tied to the event.
location	string	UUID of the location.
location_notes	string	Notes about the location.
judge_name	string	Judge for the event. Defaults to the agency's default judge when set.
flow	string	UUID of the flow that schedules this event's reminders.
portal	string	UUID of the portal that hosts the event's page.
virtual	boolean	Whether the event is virtual.
virtual_notes	string	Notes for a virtual event, such as a join link.
description	string	Short description of the event.
notes	string	Additional notes.
code	string	Agency-defined code.
url	string	Unique slug for the event's link. Generated automatically.
upload	string	UUID of the file import associated with the event, when linked to one.
created_by	string	Email or UUID of the creator, for events created through the app or a file import. Events created through this API do not set it.
created_at	string	Creation timestamp, UTC.
updated_at	string	Last update timestamp, UTC.
archived_at	string	Set when the event is archived, otherwise null.
deleted_at	string	Set when the event is deleted, otherwise null.

A single-event response also includes computed fields: timezone (the agency timezone), flow_name and location_name, the client's first_name, last_name, client_uuid, and language, a combined date_time, and the booleans is_now and is_past.

Create an Event

POST /v1/events

Request:

curl -X POST "$BASE_URL/v1/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "{client_uuid}",
    "event_reference": "EVENT-12345",
    "case_number": "CASE-2024-001",
    "date": "2024-03-15",
    "time": "09:00",
    "type": "hearing",
    "status": "scheduled",
    "description": "Initial hearing"
  }'

Response (201):

{
  "uuid": "{event_uuid}",
  "client": "{client_uuid}",
  "event_reference": "EVENT-12345",
  "case_number": "CASE-2024-001",
  "date": "2024-03-15",
  "time": "09:00",
  "type": "hearing",
  "status": "scheduled",
  "description": "Initial hearing",
  "flow": "{flow_uuid}",
  "portal": "{portal_uuid}",
  "location": "{location_uuid}",
  "virtual": 0,
  "url": "aB3dE5fG7hJ9",
  "timezone": "America/New_York",
  "created_at": "2024-03-01 14:22:05"
}

Request Fields and Defaults

date is required; a create without a usable date returns 400 with Date required. Every other field is optional:

Field	Default when omitted
date	Required. start_date is accepted in its place. Alternatively send date_time (a combined date and time in the agency timezone) and the API splits it into date and time.
time	Empty. start_time is accepted in its place.
client / client_reference	No client is attached. Events without a client do not generate reminders. See Attaching a Client.
flow	The agency's default flow. Identify a specific flow with flow (UUID), flow_reference, or its name.
location	The agency's default location.
portal	The agency's default portal.
judge_name	The agency's default judge, when configured.
virtual	0. Set to a truthy value (1, true, yes, y) to mark the event virtual.
url	A unique random slug is generated.

Attaching a Client

Identify the client with client (UUID), client_uuid (UUID), or client_reference (your client identifier). The client is the recipient of the event's reminder messages. An event with no client is created but generates no reminders. To attach more than one client to a single event, see Attaching Additional Clients.

What Happens After Create

Unless the event date is more than 90 days in the past, the event is processed after it is created:

1. If a client is attached, an event_created auto message trigger fires (plus event_status when a status is set, and event_appeared when an appearance outcome is set).
2. The event is queued for processing, which schedules reminder messages from the flow.

Pass "skip_sync": true in the request body to save the event without either scheduling reminders or firing the create-time auto messages.

List Events

GET /v1/events

curl -X GET "$BASE_URL/v1/events?from_date=2024-03-01&to_date=2024-03-31&type=hearing&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Response (200): a JSON array of event objects.

Query Parameters

Filtering:

Parameter	Description
search	Partial match on event_reference.
event_reference	Exact match on event_reference.
case_number	Exact match on case number.
type	Exact match on type.
status	Exact match on status.
appeared	Exact match on appearance outcome.
date	Exact match on date.
end_date	Exact match on end date.
from_date	Events with date on or after this date (YYYY-MM-DD).
to_date	Events with date on or before this date.
from_time	Events with time on or after this time (HH:MM).
to_time	Events with time on or before this time.
judge	Exact match on judge. judge_name is an accepted alias.
description	Exact match on description.
location_notes	Partial match on location notes.
virtual_notes	Partial match on virtual notes.
virtual	Set to 1 to return only virtual events.
client	Filter by client UUID. Use client=none to return only events with no client attached.
search_clients	Return events for clients matching this name search.
upload	Filter by the file import (upload) UUID that created the events.
created_by	Filter by the creator's email or UUID.

Combine from_date and to_date (both inclusive) for calendar ranges, for example events this month or a specific hearing day. Pagination and shaping follow the shared conventions.

Get an Event

GET /v1/events/{uuid}

The path value accepts an event UUID or an event_reference. Returns the event object with the computed fields (flow_name, location_name, client name fields, date_time, is_now, is_past, timezone). Returns 404 with a message of Event {uuid} not found when no event matches.

curl -X GET "$BASE_URL/v1/events/EVENT-12345" \
  -H "Authorization: Bearer $TOKEN"

Update an Event

PATCH /v1/events/{uuid}

PUT is an accepted alias. Send only the fields you want to change; the event is reprocessed after the update, so its reminders are rescheduled from the current data. The response returns the event's stored fields plus timezone, not the computed fields a GET returns, and virtual comes back as 0 or 1. Returns 404 with Event {uuid} not found when no event matches.

curl -X PATCH "$BASE_URL/v1/events/{event_uuid}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-03-22",
    "time": "10:30",
    "status": "rescheduled"
  }'

Rescheduling an event to a new date is a common update: change date (and time), and the reminders reschedule around the new date automatically.

Reprocess an Event

POST /v1/events/{uuid}/process

Queues the event for processing, rebuilding its reminder schedule from the flow and the event's current data. /v1/events/{uuid}/sync behaves identically, and both return the same response. Returns 400 with Valid uuid required when the path value is not a valid UUID.

Response (202):

{"message": "Syncing Event"}

Attaching Additional Clients

An event can notify more than one client (for example, several parties tied to the same hearing). The primary recipient is the event's client; use these endpoints to attach others.

POST /v1/events/{uuid}/attach
GET  /v1/events/{uuid}/attached
DELETE /v1/events/{uuid}/detach

• Attach takes a client (required) and adds them to the event. Returns 201 with the attachment record, 400 with Client is required when no client is sent, or 409 with Client is already attached when the client is already on the event.
• Attached returns the event's attachment records (each with uuid, event, and the client UUID), not full client objects.
• Detach takes a client (a UUID, required) and removes them, and also hard-deletes that client's unsent outbound messages for the event (up to 100). Returns 202 with {n} clients detached, 404 with Client not found when the client was not attached, or 400 with Client is required.

curl -X POST "$BASE_URL/v1/events/{event_uuid}/attach" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "{client_uuid}"}'

Archive, Restore, and Delete

PUT /v1/events/{uuid}/archive
PUT /v1/events/{uuid}/restore
DELETE /v1/events/{uuid}

• Archive sets archived_at, removes the event from default lists, and cancels its scheduled, unsent reminders. Returns {"message": "Event {uuid} archived"}.
• Delete is a soft delete: it sets deleted_at and cancels the event's scheduled, unsent reminders. Returns a 204 with no body, or 404 when no event matches.
• Restore clears archived_at and deleted_at and reprocesses the event, rescheduling reminders. Returns {"message": "Event {uuid} restored"}.

FAQs

How do I schedule reminders for a court date?

Create an event with a client and a date (and time). eCourtDate schedules reminder messages from the event's flow and sends them to the client's contacts ahead of the date. If no flow is specified, the agency's default flow is used.

How do I reschedule an event?

PATCH /v1/events/{uuid} with the new date (and time). The update reprocesses the event, so pending reminders reschedule around the new date. Messages already sent are not affected.

Why are no reminders going out for an event?

The most common causes: the event has no client attached (check the client field), the client has no opted-in contacts, the event has no flow with messages, or the event date is more than 90 days in the past (past events are not processed). Reprocess with POST /v1/events/{uuid}/process after fixing the data.

How do I list events in a date range?

Use from_date and to_date (both inclusive, YYYY-MM-DD): GET /v1/events?from_date=2024-03-01&to_date=2024-03-31. Add from_time and to_time to bound the time of day, or type/status to narrow further.

Can one event notify more than one person?

Yes. The event's client is the primary recipient. Attach others with POST /v1/events/{uuid}/attach, list them with GET /v1/events/{uuid}/attached, and remove one with DELETE /v1/events/{uuid}/detach.

How do I find events with no client assigned?

GET /v1/events?client=none returns only events that have no client attached, which is useful for catching imported events that failed to match a client.

What timezone are event dates in?

date, time, and their end counterparts are interpreted in the agency's timezone, which is returned as timezone on the event. Timestamps such as created_at are UTC.

Related Documentation

• API Conventions: shared listing, filtering, and lifecycle behavior
• Clients: the person an event notifies
• Merge Tags: event tags in message templates
• Common Concepts: how events relate to other records
• Error Handling: status codes and error responses