Clients

A client is a person the agency communicates with: a defendant, a juror, a participant, or any individual tracked in the platform. The client is the central record that events, contacts, cases, payments, and messages link to. This page covers creating and managing clients, including attaching phone and email contacts in the same request.

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/clients`	List clients
`GET`	`/v1/clients/total`	Count clients matching filters
`GET`	`/v1/clients/duplicates`	Find field values shared by more than one client
`GET`	`/v1/clients/{uuid}`	Get a single client (by UUID or `client_reference`)
`GET`	`/v1/clients/{uuid}/users`	List users assigned to a client
`GET`	`/v1/clients/{client_reference}/duplicates`	List clients that share a client reference
`POST`	`/v1/clients`	Create a client
`PATCH`	`/v1/clients/{uuid}`	Update a client
`PUT`	`/v1/clients/{uuid}`	Update a client (alias of `PATCH`)
`POST`	`/v1/clients/{uuid}/sync`	Reschedule the client's event and payment reminders
`POST`	`/v1/clients/merge`	Merge one client's records into another
`POST`	`/v1/clients/transfer`	Transfer a client (asynchronous)
`PUT`	`/v1/clients/{uuid}/archive`	Archive a client and its related records
`PUT`	`/v1/clients/{uuid}/restore`	Restore an archived or deleted client
`DELETE`	`/v1/clients/{uuid}`	Delete a client and its related records (soft delete)

The Client Object

Field	Type	Description
`uuid`	string	Unique identifier, generated when the client is created.
`client_reference`	string	Your identifier for the client, such as a case-management system ID. The recommended key for syncing with an external system.
`first_name`	string	Given name.
`middle_name`	string	Middle name.
`last_name`	string	Family name.
`name`	string	Display name. Computed from the name parts using the agency's display format when not set explicitly.
`aliases`	string	Other names the client is known by.
`language`	string	Preferred language code, such as `en` or `es`. Defaults to `en` when omitted.
`group`	string	Agency-defined grouping.
`type`	string	Agency-defined client type.
`status`	string	Agency-defined status.
`dob`	string	Date of birth (`YYYY-MM-DD`).
`gender`	string	Normalized to `m`, `f`, `n` (non-binary), or `u` (unknown) on read.
`race`	string	Race.
`marital_status`	string	Marital status.
`birth_place`	string	Place of birth.
`birth_country`	string	Country of birth.
`citizenship`	string	Citizenship.
`notes`	string	Free-text notes.
`upload`	string	UUID of the file import associated with the client, when linked to one.
`created_by`	string	Email or UUID of the user or API client that created the client.
`created_at`	string	Creation timestamp, UTC.
`updated_at`	string	Last update timestamp, UTC.
`archived_at`	string	Set when the client is archived, otherwise `null`.
`deleted_at`	string	Set when the client is deleted, otherwise `null`.

A single-client response also includes users, the list of users assigned to the client (each with uuid, name, and email).

Create a Client

POST /v1/clients

Request:

curl -X POST "$BASE_URL/v1/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "client_reference": "CLIENT-12345",
    "language": "en",
    "phone": "+15551234567",
    "email": "jane.doe@example.com"
  }'

Response (201):

{
  "uuid": "{client_uuid}",
  "first_name": "Jane",
  "last_name": "Doe",
  "name": "Jane Doe",
  "client_reference": "CLIENT-12345",
  "language": "en",
  "client": "{client_uuid}",
  "created_by": "integration@agency.gov",
  "created_at": "2024-03-01 14:22:05"
}

Attaching Contacts on Create

You can create the client's contacts in the same request instead of making separate calls to the Contacts endpoint:

Field	Creates
`phone`	One text contact.
`phones`	Multiple text contacts, comma-separated.
`email`	One email contact.
`emails`	Multiple email contacts, comma-separated.
`contact`	One contact; the channel is detected from the value: a valid email address becomes an email contact, a valid phone number becomes a text contact, and a value that is neither is ignored.

Phone values are normalized to E.164 (see Contacts). To create these contacts already opted out or with notifications off, add optin: "n" or notify: "n" to the request; they apply to the contacts created in this call.

Required Fields and Duplicate Handling

Two agency settings shape create behavior:

Required fields: an agency can require fields (for example a name, or a phone or email). When a required field is missing, the API returns a validation error. Pass ignore_required: true to bypass this check. The special requirement phone_or_email is satisfied by sending either a phone or an email.
Duplicate checking: when the agency has configured duplicate keys, and a new client matches an existing one on those keys, the API returns the existing client (uuid, client_reference, first_name, last_name, created_at) with a 200 status instead of creating a new record (201). Check the status code to tell the two cases apart.

Other Create Behavior

full_name: send full_name instead of separate name fields and the API splits it into first_name and last_name. Only the first two space-separated parts are used, so send the fields separately for names that do not split into two parts.
client_reference: optional. When omitted and the agency has auto-reference enabled, a random 12-character reference is generated.
language: defaults to en (the platform default) when omitted.
group: sending group: "random" assigns a random group from the agency's configured default groups.
Creating a client triggers a client_created auto message (and client_status or client_group triggers when those fields are set), so an agency can send a welcome or enrollment message automatically.

List Clients

GET /v1/clients

curl -X GET "$BASE_URL/v1/clients?last_name=Doe&status=active&limit=50" \
  -H "Authorization: Bearer $TOKEN"

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

Query Parameters

Filtering:

Parameter	Description
`client_reference`	Exact match on your client identifier.
`name`	Partial match on the display name.
`first_name`	Partial match on first name.
`middle_name`	Partial match on middle name.
`last_name`	Partial match on last name.
`aliases`	Partial match on aliases.
`language`	Exact match on language code.
`group`	Exact match on group.
`type`	Exact match on type. `client_type` is an accepted alias.
`status`	Exact match on status. `client_status` is an accepted alias.
`dob`	Exact match on date of birth.
`created_by`	Exact match on the creator.
`upload`	Filter by the file import (upload) UUID that created the clients.
`users`	Filter by assigned user UUIDs (comma-separated).
`organizations`	Filter by organization UUIDs (comma-separated).

Add total=true to receive a {"total": <count>, "data": [...]} envelope instead of a bare array, which returns the page of records and the total count together. Pagination and shaping follow the shared conventions: limit, skip, sort, sortDirection, and fields.

Get a Client

GET /v1/clients/{uuid}

The path value accepts a client UUID or a client_reference. Returns the client object, including the computed name, normalized gender, and assigned users. Returns 404 with a message of Client {uuid} not found when no client matches.

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

Update a Client

PATCH /v1/clients/{uuid}

PUT is an accepted alias. The path value accepts a UUID or a client_reference. Send only the fields you want to change.

curl -X PATCH "$BASE_URL/v1/clients/{client_uuid}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "language": "es"
  }'

Response (200): the updated fields, plus the client's assigned users.

Updating a client reschedules the reminder messages for the client's upcoming events and payments, so changes that affect messaging (such as language) flow through to pending reminders. Pass skip_sync: true to update without rescheduling. Updates also trigger a client_updated auto message (and client_status or client_group when those fields are set).

Sync a Client

POST /v1/clients/{uuid}/sync

Queues a rebuild of the reminder messages for the client's upcoming events and payments, using the client's current data and contacts. Use this after changing a client's contacts or details to bring pending reminders in line.

Response (202):

{"message": "Syncing client"}

Find Duplicates

GET /v1/clients/duplicates

Returns the values of one field that appear on more than one active client, useful for finding accidental duplicate records. Set field to any client field (default client_reference); an unknown field returns 400 with Unknown Client field. Results are capped at 10 values.

curl -X GET "$BASE_URL/v1/clients/duplicates?field=client_reference" \
  -H "Authorization: Bearer $TOKEN"

Response (200):

{
  "total": 2,
  "results": [
    {"client_reference": "CLIENT-12345"},
    {"client_reference": "CLIENT-67890"}
  ]
}

To list the individual clients that share a specific reference, use GET /v1/clients/{client_reference}/duplicates.

Merge Clients

POST /v1/clients/merge

Reassigns a client's cases, messages, contacts, and events from one client to another, consolidating duplicate records. Both from_client and to_client must be client UUIDs.

curl -X POST "$BASE_URL/v1/clients/merge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_client": "{duplicate_client_uuid}",
    "to_client": "{surviving_client_uuid}"
  }'

Response (200): an array of the tables updated and how many records moved. The table values are the underlying tables whose records were reassigned, so case records appear as client_cases:

[
  {"count": 2, "table": "client_cases"},
  {"count": 3, "table": "messages"},
  {"count": 1, "table": "contacts"}
]

Only tables that had records to move appear in the response. Returns 400 with A valid from_client uuid is required (or to_client) when either value is missing or not a UUID. Merging moves the related records but does not delete the from_client; delete or archive it separately if it is no longer needed.

Transfer a Client

POST /v1/clients/transfer

Queues a transfer of the client identified by client (a UUID). The transfer runs asynchronously.

Response (202):

{"message": "Processing transfer"}

Returns 400 with Invalid Client when client is missing or not a UUID.

Archive, Restore, and Delete

Archiving, deleting, and restoring a client cascade to the client's related records:

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

Archive sets archived_at on the client and its events, contacts, and cases, soft-deletes (deleted_at) the client's unsent messages, cancels the client's scheduled messages, and removes the client from default lists. Returns {"message": "Archived Client {uuid} and related data"}.
Delete is a soft delete: it sets deleted_at on the client and its events, contacts, cases, and unsent messages. Returns a 204 with no body.
Restore clears archived_at and deleted_at on the client and un-archives or un-deletes its events, contacts, and cases, then reschedules the client's event and payment reminders. Messages soft-deleted when the client was archived or deleted are not brought back; fresh reminders are regenerated instead. Returns {"message": "Restoring Client {uuid} and related data"}.

Because these actions cascade, archiving or deleting a client stops all of that client's pending reminders in one call.

FAQs

How do I look up a client by my own system's ID?

Use client_reference. You can filter the list (GET /v1/clients?client_reference=CLIENT-12345) or pass the reference directly in the path of a get or update (GET /v1/clients/CLIENT-12345). Set client_reference on create so it is available for later lookups.

How do I add a client's phone and email in one request?

Include phone and email (or phones and emails for multiple, comma-separated) on the create request. eCourtDate creates the matching contacts and normalizes phone numbers to E.164. Add optin: "n" or notify: "n" to create those contacts opted out or with notifications off.

What happens if I create a client that already exists?

When the agency has duplicate checking configured, a matching create returns the existing client with a 200 status instead of creating a new record (201). Check the status code, or search first with GET /v1/clients?client_reference=..., to avoid duplicates.

How do I merge two duplicate clients?

POST /v1/clients/merge with from_client and to_client (both UUIDs) moves the duplicate's cases, messages, contacts, and events to the surviving client. Then archive or delete the now-empty from_client. To find duplicates in the first place, use GET /v1/clients/duplicates?field=client_reference.

Can I send a single name field instead of first and last name?

Yes. Send full_name and the API splits it into first_name and last_name, using the first two space-separated parts. Send the fields separately for names that do not split cleanly.

What happens to a client's events, contacts, and messages when I delete the client?

Deleting or archiving a client cascades to its events, contacts, and cases, soft-deletes the client's unsent messages, and cancels the client's scheduled reminders. Restoring the client un-archives or un-deletes its events, contacts, and cases and reschedules reminders; previously deleted messages are not restored, since fresh reminders are regenerated.

API Conventions: shared listing, filtering, and lifecycle behavior
Contacts: the client's phone and email contacts
Payments: balances owed by a client
Common Concepts: how clients relate to other records
Error Handling: status codes and error responses

Endpoints​

The Client Object​

Create a Client​

Attaching Contacts on Create​

Required Fields and Duplicate Handling​

Other Create Behavior​

List Clients​

Query Parameters​

Get a Client​

Update a Client​

Sync a Client​

Find Duplicates​

Merge Clients​

Transfer a Client​

Archive, Restore, and Delete​

FAQs​

Related Documentation​