Common Concepts

This page describes the core domain model and conventions used throughout eCourtDate. Understanding these concepts will help you navigate the platform, whether you work through the Admin Application, the API, SFTP, or a combination of all three.

Platform Overview

Before diving into individual resource types, here is how data typically flows through eCourtDate:

1. Data enters eCourtDate: Records are created through any combination of data sources — file imports (SFTP or Admin Application upload), API calls, manual entry in the Admin Application, Portal Application submissions, or third-party integrations. This creates Clients, Events, Contacts, Cases, Payments, and other records.
2. Automation runs: Based on how the agency is configured, eCourtDate can generate and schedule messages, process payments, trigger workflows, and update records automatically.
3. People interact: Individuals can receive notifications, respond to messages, view upcoming events, make payments, complete forms, and update their contact information through the Portal Application.
4. Everything is tracked: Activity across the platform — delivery statuses, payment outcomes, form submissions, record changes — is recorded and available in the Admin Application and via the API.

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

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 across the platform.

If your agency uses the API, always store the uuid returned in responses. You will need it to reference that resource in subsequent requests (updates, lookups, associations). UUIDs are also visible in the Admin Application and in SFTP acknowledgement files.

{
  "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, equivalent to a tenant. Each agency has completely isolated data, configuration, and user access. One agency cannot see or access another agency's data.

What's isolated per agency

Every agency maintains its own independent set of:

• Data: Clients, events, messages, cases, contacts, payments, and all other records
• Configuration: Flows, templates, settings, and delivery preferences
• Users and roles: Each agency has its own user list with independently assigned roles and permissions
• API credentials: API clients and keys are scoped to a single agency
• SFTP profiles: Separate SFTP credentials and directory structures
• Webhooks and domains: Webhook endpoints and custom domains are configured per agency

Multi-agency access

A single user can belong to multiple agencies. Roles and permissions are assigned per agency independently — being an admin in one agency does not grant admin access in another. Users switch between agencies in the Admin Application without needing separate login credentials.

Staging and production

It is recommended to create separate staging and production agencies. Because agencies are fully independent, changes in a staging agency do not affect production. Use staging to test new workflows, templates, and integrations without risk. Each agency has its own API credentials, SFTP profiles, and configuration, so staging and production never share state.

API access is optional

Not every agency needs API access. Agencies can operate entirely through the Admin Application, SFTP, or the Portal Application without ever creating an API client.

Data Sources

eCourtDate supports multiple simultaneous data sources per agency. Agencies can use any combination of the methods below, and most use more than one.

Source	Description	Best For
SFTP	Automated file transfers (CSV, TXT, XLSX) processed through Upload Templates.	Recurring bulk imports from case management or records systems.
API	Programmatic record creation and updates via REST API.	Real-time integrations, custom applications, bidirectional sync.
Admin Application Uploads	Manual file uploads through the Admin Application.	Ad-hoc imports, one-time data loads, corrections.
Admin Application Manual Entry	Create and edit records directly in the Admin Application.	Individual record management, small-volume updates.
Portal Application	Individuals submit forms, update contact info, and make payments through public-facing portals.	Public-facing data collection, contact updates, payments.
Third-Party Integrations	Pre-built connectors (Tyler Odyssey, NetData, Workday, etc.).	Agencies using supported systems.

All data sources write to the same underlying records. A client created via SFTP can receive a payment through the portal and have their record updated via the API — all within the same agency.

For more details, see SFTP and API Guide.

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 can be delivered via text (SMS), email, voice, or push. They can be created automatically through flows and auto messages, manually by users, in bulk through bulk actions, or programmatically via the API.

For full details on message creation, delivery channels, scheduling, send modes, statuses, and SMS encoding, see Messaging Concepts.

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. This applies across the platform — API responses, SFTP files, exports, and webhook payloads.
• All phone numbers should be provided in E.164 format (e.g., +15551234567) regardless of how data is submitted.
• UUIDs: Every resource includes a uuid. If your agency uses the API, always persist this value for future operations.
• Pagination: API list endpoints return paginated results. Use the pagination parameters documented in each endpoint's reference.

Next Steps

• Messaging Concepts: How messages are created, delivered, scheduled, and tracked.
• 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.