Common Concepts

This page describes the core domain model and conventions used throughout the eCourtDate API. Understanding these concepts will help you navigate the API and build integrations more effectively.

How It All Fits Together

Before diving into individual resource types, here's a typical end-to-end workflow showing how data flows through eCourtDate:

1. Your court exports hearing data — Your case management system generates a file containing upcoming hearings, defendant information, and contact details.
2. eCourtDate imports the data — The file is uploaded (manually or via SFTP) and processed using an Upload Template. This creates Clients (people), Events (hearings), and Contacts (phone numbers and email addresses).
3. Messages are automatically generated — Based on your configured messaging flows, eCourtDate creates Messages — such as court date reminders — and schedules them for delivery.
4. Messages are delivered — Messages go out via SMS, email, or voice through the configured delivery channels.
5. Delivery status is tracked — eCourtDate records whether each message was delivered, failed, or received a response, making the status available in the Console and via the API.

Each of the resources described below plays a role in this workflow.

UUIDs

Every resource in eCourtDate is assigned a globally unique identifier (uuid) when it is created. The uuid is the primary identifier used to retrieve, update, and delete resources through the API.

Always store the uuid returned in API responses. You will need it to reference that resource in subsequent requests (updates, lookups, associations).

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-03-15T14:30:00Z",
  "...": "..."
}

References

In addition to UUIDs, many resources support human-readable reference fields that map to identifiers in your existing systems:

• client_reference -- A reference value you assign to a client record (e.g., a defendant ID or person number from your case management system).
• event_reference -- A reference value you assign to an event record (e.g., a hearing ID or docket number).

References make it easier to correlate eCourtDate records with records in external systems. They are searchable and can be used as lookup keys in many API endpoints.

Agencies

An agency is the top-level organizational unit in eCourtDate. Each agency represents a court, prosecutor's office, or other organization and has its own configuration, users, data, and API credentials. All resources belong to an agency, and API keys are scoped to a single agency.

Clients

A client represents an individual person who interacts with the justice system. Clients can be defendants, victims, witnesses, jurors, or staff members. Each client record contains identifying information:

Field	Description
uuid	Unique identifier assigned by eCourtDate.
client_reference	Your external identifier for this person.
first_name	The client's first name.
last_name	The client's last name.
group	Role or category (e.g., defendant, victim, juror).

A single client can be associated with multiple contacts, events, cases, and messages.

Events

An event represents a scheduled occurrence such as a court hearing, appointment, or check-in. Events are the primary driver for automated reminders and notifications.

Field	Description
uuid	Unique identifier assigned by eCourtDate.
event_reference	Your external identifier for this event.
scheduled_at	The date and time of the event (ISO 8601).
timezone	The timezone for the event (e.g., America/New_York).
location	Where the event takes place.
flow	The messaging flow associated with this event.

Contacts

A contact is a phone number or email address associated with a client. Contacts are the delivery endpoints for messages.

Field	Description
uuid	Unique identifier assigned by eCourtDate.
phone	Phone number in E.164 format (e.g., +15551234567).
email	Email address.
type	Contact type (e.g., mobile, home, work).

A client can have multiple contacts. When a message is sent, eCourtDate uses the associated contacts to determine where to deliver it.

Messages

A message is a single communication sent or received through eCourtDate. Messages support multiple channels:

Field	Description
uuid	Unique identifier assigned by eCourtDate.
direction	outbound (sent by the agency) or inbound (received from a contact).
channel	Delivery channel: text, email, or voice.
status	Current delivery status (e.g., queued, sent, delivered, failed).
content	The message body.
subject	Subject line (used for email).
send_now	When true, the message is sent immediately rather than queued for scheduled delivery.
skip_duplicate	When true, prevents sending a duplicate message to the same contact for the same event.

Cases

A case tracks a legal case or matter within the system.

Field	Description
uuid	Unique identifier assigned by eCourtDate.
case_number	The official case number used by the court or agency.

Cases can be linked to clients, events, and other resources to provide context for communications.

Payments

A payment represents a financial transaction processed through eCourtDate.

Field	Description
uuid	Unique identifier assigned by eCourtDate.
amount	The payment amount.
reference	A reference identifier for the payment (e.g., receipt number or invoice ID).
status	Current payment status.

Additional Resources

Other resource types you may encounter in the API include:

• Warrants -- Active warrant records associated with clients.
• Bonds -- Bond and bail information.
• Forms -- Digital forms for data collection.

Key Conventions

• All timestamps are in ISO 8601 format and stored in UTC unless a timezone field is present.
• All phone numbers should be provided in E.164 format (e.g., +15551234567).
• All API responses include the uuid of the created or modified resource. Always persist this value for future operations.
• Pagination -- List endpoints return paginated results. Use the pagination parameters documented in each endpoint's reference.

Next Steps

• Quickstart -- Put these concepts into practice by sending your first message.
• API Reference -- Browse detailed endpoint documentation for each resource type.
• Environments & Regions -- Understand where your API requests are routed.