Skip to main content

API Reference

Complete endpoint reference for the eCourtDate REST API. All endpoints require authentication via Bearer token. See Authentication.

tip

Explore the API interactively using our Postman Workspace.

Base URL​

Use the base URL for your assigned region. See Environments & Regions for the full list.

https://{region}.api.ecourtdate.com

Authentication​

POST /oauth/token

Request a Bearer token using client credentials.

Request:

{
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "grant_type": "client_credentials"
}

Response (201):

{
  "access_token": "{access_token}",
  "token_type": "Bearer"
}

Settings​

Get Settings​

GET /v1/settings

Verify API access and retrieve agency configuration. Use ?agency_reference={ref} for multi-agency access.

Clients​

A client is a person the agency communicates with. It is the central record that contacts, events, cases, payments, and messages link to.

See the full Clients reference for the client object, attaching contacts on create, duplicate handling, merge and transfer, lifecycle cascades, and more examples.

List Clients​

GET /v1/clients

Query parameters: limit, skip, sort, sortDirection, fields, client_reference, name, first_name, middle_name, last_name, aliases, language, group, type, status, dob, created_by, upload, users, organizations. Add total=true for a {total, data} envelope.

Create Client​

POST /v1/clients

Request:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+15551234567",
  "email": "jane.doe@example.com",
  "client_reference": "CLIENT-12345",
  "language": "en"
}

Send phone/phones and email/emails to attach contacts in the same request. full_name splits into first_name and last_name. Creating a client triggers a client_created auto message.

Get Client​

GET /v1/clients/{uuid}

The path value accepts a client UUID or a client_reference.

Update Client​

PATCH /v1/clients/{uuid}

PUT is an accepted alias. Updating reschedules the client's event and payment reminders unless you pass skip_sync: true.

Merge / Transfer / Sync​

POST /v1/clients/merge
POST /v1/clients/transfer
POST /v1/clients/{uuid}/sync

Merge moves a duplicate client's records into another; transfer runs asynchronously; sync reschedules the client's event and payment reminders.

Archive / Restore / Delete​

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

These cascade to the client's events, contacts, and cases, soft-delete its unsent messages, and cancel scheduled reminders. Delete is a soft delete (204).

Clients FAQs​

How do I look up a client by my own system's ID? Filter by reference: GET /v1/clients?client_reference=CLIENT-12345. The client_reference field stores your identifier and is the recommended key for syncing with an external system.

What happens if I create a client that already exists? When the agency has duplicate checking configured (the Client Duplicates setting), POST /v1/clients returns identifying fields of the existing matching client (uuid, client_reference, first_name, last_name, created_at) with a 200 status instead of creating a new record (201). Check the response status code to tell the two cases apart.

Can I send one name field instead of first and last name? Yes. Send full_name and the API splits it into first_name and last_name when those fields are not provided. Only the first two space-separated parts are used, so first_name becomes the first word and last_name the second; send the fields separately for names that do not split cleanly into two parts.

Is client_reference required? Required fields are configured per agency. When client_reference is omitted and the agency has the Auto Client Reference setting enabled, the API generates a random 12-character value.

Events​

An event is a court date, hearing, appointment, or deadline an individual is expected to attend. Creating an event schedules reminder messages for the attached client through the event's flow.

See the full Events reference for the event object, create defaults, date filtering, attaching additional clients, reprocessing, and lifecycle actions.

List Events​

GET /v1/events

Query parameters: limit, skip, sort, sortDirection, fields, search, event_reference, case_number, type, status, appeared, date, from_date, to_date, from_time, to_time, judge, virtual, client (or client=none), search_clients, upload, created_by

Create Event​

POST /v1/events

Request:

{
  "client": "{client_uuid}",
  "case_number": "CASE-2024-001",
  "event_reference": "EVENT-12345",
  "date": "2024-03-15",
  "time": "09:00",
  "type": "hearing",
  "description": "Initial hearing",
  "status": "scheduled",
  "location": "{location_name_or_reference}",
  "flow": "{flow_name_or_reference}",
  "portal": "{portal_name_or_reference}"
}

date is required (400 with Date required otherwise). location, flow, and portal accept a UUID, name, or reference and default to the agency defaults. Attach the client with client (UUID) or client_reference.

Get Event​

GET /v1/events/{uuid}

The path value accepts an event UUID or an event_reference.

Update Event​

PATCH /v1/events/{uuid}

PUT is an accepted alias. The event is reprocessed after an update, so reminders reschedule around the current data.

Attach / Detach Clients​

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

Attach additional clients to an event so it notifies more than one person.

Reprocess Event​

POST /v1/events/{uuid}/process

Rebuilds the event's reminder schedule from its flow. Returns 202.

Archive / Restore / Delete​

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

Archiving and deleting cancel the event's scheduled, unsent reminders. Delete is a soft delete (204).

Events FAQs​

How do I list events in a date range? Use from_date and to_date (inclusive, YYYY-MM-DD): GET /v1/events?from_date=2024-03-01&to_date=2024-03-31. Narrow by time of day with from_time and to_time.

What does the search parameter match on events? Partial matches on event_reference only. To filter by other fields, use the dedicated parameters: case_number, type, status, date, judge_name, or description (exact match).

How do I filter virtual events? GET /v1/events?virtual=1. The values true, yes, and y also work.

How do I find events imported from a specific file? Events created by a file import carry the import's UUID: GET /v1/events?upload={upload_uuid}.

Contacts​

List Contacts​

GET /v1/contacts

Query parameters: limit, skip, sort, sortDirection, client

A contact is one way to reach a client: a channel (text, voice, or email) plus a value (a phone number or email address). A client can have many contacts. Messages are sent to a client's contacts that are opted in and set to notify.

See the full Contacts reference for the contact object, channel and value normalization, opt-in and opt-out, validity, and more examples.

Create Contact​

POST /v1/contacts

Request:

{
  "client_reference": "CLIENT-12345",
  "value": "+15551234567",
  "channel": "text",
  "name": "Mobile"
}

Send the contact point in value (a phone number for text/voice, an email address for email) and set channel. Phone numbers are normalized to E.164 (US assumed), so (555) 123-4567 stores as +15551234567. optin, notify, and primary default to 1. Attach the client with client (UUID) or client_reference. A duplicate value and channel returns 409 with Contact {value} already exists.

Get Contact​

GET /v1/contacts/{uuid}

The path value accepts a contact UUID, a phone number, or an email address.

Update Contact​

PATCH /v1/contacts/{uuid}

PUT is an accepted alias. Send only the fields to change. optout: true sets optin to 0; invalid: true sets valid to 0.

Opt In / Opt Out​

PUT /v1/contacts/{uuid}/optin
PUT /v1/contacts/{uuid}/optout

Opt in sets optin and notify to 1. Opt out sets both to 0 and cancels the contact's scheduled, unsent messages. The path value accepts a UUID or a raw phone number or email address.

Archive / Restore Contact​

PUT /v1/contacts/{uuid}/archive
PUT /v1/contacts/{uuid}/restore

Delete Contact​

DELETE /v1/contacts/{uuid}

Soft delete. Cancels the contact's scheduled, unsent messages. Returns 204.

Contacts FAQs​

What is the difference between a client and a contact? A client is the person; a contact is one way to reach them, a channel (text, voice, or email) plus a value. A client can have multiple contacts, and messages go to the client's contacts that are opted in and set to notify.

How do I specify whether a contact is a phone or an email? Set the channel field: text or voice for a phone number, email for an email address. Setting it explicitly is the reliable approach; sending an email address in the contact field sets the channel to email automatically.

What is the difference between optin, notify, and valid? optin records consent to receive messages, notify controls whether notifications are sent, and valid reflects whether the value is a deliverable phone number or email address. A contact receives messages only when it is opted in, set to notify, and valid.

What happens if I add a contact that already exists? POST /v1/contacts returns 409 with a message of Contact {value} already exists for a duplicate. When the request includes a client, the check is scoped to that client (same channel and value on the same client); without a client, any active contact in the agency with the same channel and value triggers the conflict.

How do I list only opted-in or valid contacts? Use the filters on GET /v1/contacts: optin=1 or optout=1 for opt-in status, valid=1 or invalid=1 for validation status, channel to restrict to one channel, and client={client_uuid} to scope to one client.

More questions are covered in the Contacts reference FAQs.

Messages​

A message is a single communication to one recipient over text, email, or voice. Send it directly, schedule it, and attach it to a client, event, payment, case, or form so its merge tags resolve.

See the full Messages reference for the message object, scheduling and send-now, bulk sending, resend and delay, delivery tracking, and lifecycle.

List Messages​

GET /v1/messages

Returns a {data} envelope (add total=true for {total, data}), not a bare array. Query parameters: limit, skip, sort, sortDirection, fields, client (or clients), event, payment, case, form, file, status, type, channel, direction, from, to, sent, token, location, subject, content, language, error_code, test, live

Send One-Off Message​

POST /v1/messages/oneoffs

Request:

{
  "to": "+15551234567",
  "subject": "Court Reminder",
  "content": "Your hearing is scheduled for March 15 at 9:00 AM."
}

Response:

{
  "uuid": "{message_uuid}",
  "from": "+15559876543",
  "to": "+15551234567",
  "channel": "text",
  "subject": "Court Reminder",
  "content": "Your hearing is scheduled for March 15 at 9:00 AM.",
  "last_status": "scheduled",
  "sent": 0,
  "mms": 0,
  "scheduled_at": "2024-03-01 14:52:05"
}

Optional parameters:

ParameterTypeDescription
scheduled_atstringSchedule for future delivery (YYYY-MM-DD HH:MM:SS)
timezonestringTimezone for scheduling (e.g., America/New_York)
send_nowbooleanSend immediately (requires the agency's Default Message Delay to be 0 so the message is not scheduled into the future; does not apply to MMS)
skip_duplicatebooleanSkip duplicate checking
typestringMessage type
eventstringAssociated event UUID
casestringAssociated case UUID
clientstringAssociated client UUID
paymentstringAssociated payment UUID
formstringAssociated form UUID

Send Bulk Messages​

POST /v1/messages/bulks

Send many messages in one request by passing a messages array; each entry follows the same rules as a one-off, and invalid entries are skipped. Split very large sends across multiple requests within your rate limits.

Send to Clients​

POST /v1/messages

Send to one or more clients by UUID (client or clients) and let eCourtDate resolve their contacts.

Get Message​

GET /v1/messages/{uuid}

The path value accepts a message UUID or a token.

Update / Delete Scheduled Message​

PATCH /v1/messages/{uuid}
DELETE /v1/messages/{uuid}

Edit or cancel a message that has not sent yet. Delete is a soft delete (204).

Send Now / Dispatch / Resend / Delay​

POST /v1/messages/{uuid}/send
POST /v1/messages/dispatch
POST /v1/messages/resend
POST /v1/messages/delay

Send a scheduled message immediately, dispatch idempotently by UUID, resend recently sent messages, or delay upcoming ones.

Delivery Tracking​

GET /v1/messages/{uuid}/statuses
GET /v1/messages/{uuid}/metas
GET /v1/opens?message={message_uuid}

Messages FAQs​

Why is my message scheduled instead of sent immediately? One-off messages follow the agency's Default Message Delay setting, which schedules the message that many minutes ahead. To send immediately, pass "send_now": true and have the agency's Default Message Delay set to 0, so the message is not scheduled into the future. (The agency's Send Immediately setting is a separate path that sends without send_now.)

How do I find all messages for a specific client, event, case, or payment? Filter the list endpoint by the related record's UUID: GET /v1/messages?payment={payment_uuid}, or use the client, event, case, or form parameters the same way.

How do I check whether a message was delivered? The last_status field on the message shows the current delivery status. Call GET /v1/messages/{uuid}/statuses for a live provider lookup, or GET /v1/messages/{uuid}/metas for the full event history.

How many messages can I send in one request? One per POST /v1/messages/oneoffs request, and many per POST /v1/messages/bulks request (passed as a messages array and stored as a batch). Split very large sends across multiple requests within your rate limits.

Payments​

A payment record tracks an amount a client owes: a fine, fee, restitution, or other balance due. Creating a payment record does not charge anyone; eCourtDate uses the record to schedule reminder messages through the payment's flow, including a link the recipient uses to pay through the agency's portal.

See the full Payments reference for field descriptions, defaults, reminder scheduling behavior, and more examples.

List Payments​

GET /v1/payments

Query parameters: limit, skip, sort, sortDirection, search (partial match on payment_reference), payment_reference, client, status, type, case_number, citation, flow, portal, location, upload, due_from, due_to, issued_from, issued_to, archived, trashed

Count Payments​

GET /v1/payments/total

Returns the number of payments matching the same filters as List Payments.

List Distinct Payment Values​

GET /v1/payments/uniques?field=type

Returns the distinct values in use for type (default) or description.

Create Payment​

POST /v1/payments

Request:

{
  "client_reference": "CLIENT-12345",
  "payment_reference": "INV-2024-0042",
  "amount": 250.75,
  "type": "fine",
  "status": "outstanding",
  "issued_at": "2024-03-01",
  "due_at": "2024-03-31",
  "case_number": "CASE-2024-001",
  "description": "Traffic fine"
}

Response (201):

{
  "uuid": "{payment_uuid}",
  "client": "{client_uuid}",
  "payment_reference": "INV-2024-0042",
  "amount": 250.75,
  "raw_amount": "250.75",
  "formatted_amount": "$250.75",
  "type": "fine",
  "status": "outstanding",
  "issued_at": "2024-03-01",
  "due_at": "2024-03-31",
  "url": "aB3dE5fG7hJ9",
  "created_at": "2024-03-01 14:22:05"
}

Only amount is required (numeric, greater than zero). Attach the client with client (UUID) or client_reference. Omitted fields fall back to agency defaults: issued_at defaults to today, due_at to the agency's payment due date setting (30 days when unset), status to the agency default or draft, and flow, portal, and location to the agency defaults. Pass "skip_sync": true to create the record without scheduling reminder messages.

Get Payment​

GET /v1/payments/{uuid}

Includes computed fields (raw_amount, formatted_amount) and related record names (flow_name, location_name, portal_name).

Update Payment​

PATCH /v1/payments/{uuid}

Send only the fields to change. After an update, unsent scheduled reminders are rebuilt from the payment's current data; sent messages are unaffected.

Delete Payment​

DELETE /v1/payments/{uuid}

Soft delete. Cancels scheduled, unsent reminder messages. Returns 204.

Archive / Restore Payment​

PUT /v1/payments/{uuid}/archive
PUT /v1/payments/{uuid}/restore

Archiving removes the payment from default lists and cancels unsent reminders. Restoring clears the archived and deleted state and reschedules reminders.

Reprocess Payment​

POST /v1/payments/{uuid}/process

Rebuilds the payment's reminder schedule from its flow. Returns 202.

Payments FAQs​

Does creating a payment charge the client? No. The record tracks a balance due and drives reminder messages with a payment link. Recipients pay through the agency's portal.

How do I stop reminders once a payment is settled? Update the status to one the agency has flagged to disable messages (for example paid), or archive the payment. Both cancel unsent reminders; sent messages are never recalled.

Why is the client field missing from my create response? The client or client_reference you sent did not match an active client, so the payment was created without one. Payments without a client do not generate reminders.

Can I use my own invoice numbers? Yes, set payment_reference on create and filter with GET /v1/payments?payment_reference={value}. When omitted, a random 12-character reference is generated.

More questions are covered in the Payments reference FAQs.

Flows​

A flow is a reusable reminder schedule: it defines which messages to send and when, relative to a record's dates. Events and payments reference a flow, and its steps become their scheduled reminders.

See the full Flows reference for the flow object, message steps, create-with-steps, syncing, and lifecycle.

List Flows​

GET /v1/flows

Query parameters: limit, skip, sort, sortDirection, fields, search (partial match on name), name, flow_reference, type, status, portal, phone, email, default, virtual, simulate, created_by

Create Flow​

POST /v1/flows

Include a messages array to create the flow's steps in the same request. Each step needs a trigger and a templates object. A duplicate name or flow_reference returns 409 with Flow name must be unique.

Get / Update Flow​

GET /v1/flows/{uuid}
PATCH /v1/flows/{uuid}

The path value accepts a flow UUID or flow_reference. PATCH with {"default": true} makes this the agency's default flow.

Sync Flow​

POST /v1/flows/sync/{uuid}

Reschedules the events and payments that use the flow with its current steps. Returns 202. Editing a flow does not retroactively change already-scheduled reminders; sync applies them.

Archive / Restore / Delete​

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

Delete is a soft delete.

Cases​

A case is a matter tied to a client, identified by a case number. Events and payments carry a case_number, so a case groups the records that share it; a message links to a case by its UUID.

See the full Cases reference for the case object, attorney assignment, filtering, and lifecycle.

List / Create Case​

GET /v1/cases
POST /v1/cases

case_number is required on create (400 with Case number is required otherwise). Attach the client with client (UUID), and include an attorneys array to assign attorneys. Query parameters include search, case_number, client, status, type, charge_number, arresting_agency, the date fields, and location.

Get / Update Case​

GET /v1/cases/{uuid}
PATCH /v1/cases/{uuid}

The path value accepts a case UUID or a case_number. PUT is an accepted alias for update.

Attorneys / Archive / Restore / Delete​

GET /v1/cases/{uuid}/attorneys
PUT /v1/cases/{uuid}/archive
PUT /v1/cases/{uuid}/restore
DELETE /v1/cases/{uuid}

Delete is a soft delete (204).

Checkins​

A checkin records that an individual has reported for a court date, appointment, or service. It moves through a status (waiting to complete) and can be tied to an event and client.

See the full Checkins reference for the checkin object, create behavior, filtering, and lifecycle.

List / Create Checkin​

GET /v1/checkins
POST /v1/checkins

status defaults to waiting. Creating a checkin with a valid event UUID marks that event's appearance as checked-in. Custom fields go into the checkin's data object; send an explicit data object to control it exactly. Query parameters include search, name, client, event, status, location, service, department, virtual, inperson, and the created_from/created_to range.

Get / Update Checkin​

GET /v1/checkins/{uuid}
PATCH /v1/checkins/{uuid}

Update the status as the person progresses (for example to complete); data fields merge rather than replace.

Archive / Restore / Delete​

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

Delete is a soft delete.

Additional Resources​

Create Warrant​

POST /v1/warrants

Create Bond​

POST /v1/bonds

Create Form​

POST /v1/forms

Common Headers​

All API requests require:

Authorization: Bearer {access_token}
Content-Type: application/json

Pagination​

All list endpoints support:

ParameterDefaultDescription
limit10Records per page
skip0Records to skip
sortcreated_atSort field
sortDirectiondescasc or desc
search-Full-text search

Resources​