Contacts

A contact is a single way to reach a client: a channel (text, voice, or email) paired with a value (a phone number or an email address). A client can have many contacts, for example a mobile number for text, the same number for voice, and an email address. eCourtDate sends reminders and notifications to a client's contacts that are opted in and set to notify.

All endpoints use the base URL for your assigned region (see Environments & Regions) and require a Bearer token (see Authentication):

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

Endpoints

Method	Path	Description
GET	/v1/contacts	List contacts
GET	/v1/contacts/total	Count contacts matching filters
GET	/v1/contacts/{uuid}	Get a single contact (by UUID or by value)
POST	/v1/contacts	Create a contact
PATCH	/v1/contacts/{uuid}	Update a contact
PUT	/v1/contacts/{uuid}	Update a contact (alias of PATCH)
PUT	/v1/contacts/{uuid}/optin	Opt a contact in
PUT	/v1/contacts/{uuid}/optout	Opt a contact out
PUT	/v1/contacts/{uuid}/archive	Archive a contact
PUT	/v1/contacts/{uuid}/restore	Restore an archived or deleted contact
DELETE	/v1/contacts/{uuid}	Delete a contact (soft delete)

The Contact Object

Field	Type	Description
uuid	string	Unique identifier, generated when the contact is created.
client	string	UUID of the client this contact belongs to.
name	string	Optional label for the contact, such as Mobile, Home email, or Work.
value	string	The contact point: a phone number in E.164 format for text and voice, or an email address for email. Stored lowercase.
channel	string	How the contact is reached: text (default), voice, or email.
type	string	Optional agency-defined type.
valid	integer	1 when the value is a deliverable phone number (text and voice) or email address, 0 when it is not.
notify	integer	1 when the contact should receive notifications, 0 when it should not.
optin	integer	1 when the contact has opted in to messages, 0 when opted out.
primary	integer	1 when this is the client's primary contact.
upload	string	UUID of the file import associated with the contact, when the contact is linked to a file import.
created_by	string	Email or UUID of the user or API client that created the contact.
created_at	string	Creation timestamp, UTC, YYYY-MM-DD HH:MM:SS.
updated_at	string	Last update timestamp, UTC.
archived_at	string	Set when the contact is archived, otherwise null.
deleted_at	string	Set when the contact is deleted, otherwise null.

Create a Contact

POST /v1/contacts

Request:

curl -X POST "$BASE_URL/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "CLIENT-12345",
    "value": "+15551234567",
    "channel": "text",
    "name": "Mobile"
  }'

Response (201):

{
  "uuid": "{contact_uuid}",
  "client": "{client_uuid}",
  "name": "Mobile",
  "value": "+15551234567",
  "channel": "text",
  "notify": 1,
  "optin": 1,
  "primary": 1,
  "valid": 1,
  "created_by": "integration@agency.gov",
  "created_at": "2024-03-01 14:22:05"
}

Request Fields and Defaults

Field	Description
value	The phone number or email address, and the field you set to give the contact a reachable value. contact is an accepted alias. It is not validated at the API layer, so omitting it creates a contact with an empty value rather than returning an error; always send it. See Channel and Value for normalization.
channel	text (default), voice, or email. See Channel and Value.
client / client_reference	Attaches the contact to a client. client accepts a UUID; client_reference accepts your client identifier. Without a client, the contact is stored but no auto messages are triggered.
name	Optional label. Defaults to empty.
type	Optional agency-defined type. Defaults to empty.
optin	1 (opted in) by default. Set to 0 to create the contact already opted out.
notify	1 (notifications on) by default. Set to 0 to store the contact without sending it notifications.
primary	1 by default.
invalid	Set to true to force valid to 0 on an email contact, for example to store a known-bad address without sending to it.

Channel and Value

The channel decides how the value is interpreted and normalized:

• text (default): SMS and MMS. The value must be a phone number. It is normalized to E.164 format assuming a US number, so (555) 123-4567 and 555-123-4567 are both stored as +15551234567. If the number cannot be validated, it is stored as sent and valid is set to 0.
• voice: automated voice calls. The value must be a phone number and is normalized the same way as text.
• email: the value must be an email address. It is stored lowercase, and valid is 1 unless you pass invalid: true.

Set channel explicitly for reliable results. As a convenience, when you send an email address in the contact field, the channel is set to email automatically. Sending an email address without either setting channel: email or using the contact field stores it as a text contact with valid: 0.

Setting the Contact Name

name is a free-text label that helps staff tell a client's contacts apart, such as Mobile, Work, or Mom's phone. It does not affect delivery. Set it on create, or change it later with PATCH /v1/contacts/{uuid}.

Duplicate Handling

A contact is a duplicate when an active (not archived, not deleted) contact already has the same value and channel. When the request includes a client, the check is scoped to that client; without a client, any active contact in the agency with the same value and channel counts. On a duplicate, the API returns 409 with a message of Contact {value} already exists.

Auto Messages on Create

When a contact is created with a client attached, a contact_created auto message trigger fires. Agencies can configure an auto message for this trigger, for example to confirm an opt-in. Contacts created without a client do not trigger auto messages.

List Contacts

GET /v1/contacts

curl -X GET "$BASE_URL/v1/contacts?client={client_uuid}&channel=text&optin=1" \
  -H "Authorization: Bearer $TOKEN"

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

Query Parameters

Filtering:

Parameter	Description
client	Filter by client UUID or client_reference.
channel	Filter by channel: text, voice, or email.
value	Exact match on the stored value.
contact	Exact match on the value. A phone number is normalized to E.164 before matching.
search	Matches the value: exact for a phone number or email address, partial otherwise.
name	Partial match on the contact name.
type	Exact match on type.
optin	Set to 1 to return only opted-in contacts.
optout	Set to 1 to return only opted-out contacts.
notify	Set to 1 to return only contacts with notifications on.
valid	Set to 1 to return only valid contacts.
invalid	Set to 1 to return only invalid contacts.
upload	Filter by the file import (upload) UUID associated with the contacts.
created_by	Filter by the creator's email or UUID.
created_from	Contacts created on or after this date or datetime.
created_to	Contacts created on or before this date or datetime.
filters	A comma-separated shortcut for a single set of channel and opt-in conditions: opt-in, opt-out, text, voice, email, or archived. See the note below.
archived	Set to 1 to return only archived contacts. Archived contacts are excluded by default.
trashed	Set to 1 to return only deleted contacts. Deleted contacts are excluded by default.

The boolean filters activate only when set to a truthy value (1, true, yes, or y). To fetch opted-out contacts, use optout=1; optin=0 does not filter.

When you pass filters, it replaces the individual channel, optin, optout, notify, and valid filters rather than combining with them, so use one style or the other, not both. The client, search, contact, archived, and trashed parameters still apply alongside filters. For most cases the individual parameters above are clearer.

Pagination and shaping:

Parameter	Default	Description
limit	10	Records per page. Maximum 100.
skip	0	Records to skip.
sort	created_at	Field to sort by. Any contact field is accepted.
sortDirection	desc	asc or desc.
fields	all fields	Comma-separated list of fields to return, for example fields=uuid,value,channel,optin.

Count Contacts

GET /v1/contacts/total

Returns the number of contacts matching the same filters as List Contacts, as a bare number.

curl -X GET "$BASE_URL/v1/contacts/total?client={client_uuid}" \
  -H "Authorization: Bearer $TOKEN"

Response (200):

3

Get a Contact

GET /v1/contacts/{uuid}

Returns the contact object. The {uuid} path value can be a contact UUID, a phone number, or an email address: when it is a phone number or email, the API looks the contact up by its value. The response includes the client's language. Returns 404 with a message of Contact {uuid} not found when no contact matches.

curl -X GET "$BASE_URL/v1/contacts/{contact_uuid}" \
  -H "Authorization: Bearer $TOKEN"

Update a Contact

PATCH /v1/contacts/{uuid}

PUT is an accepted alias for the same operation. Send only the fields you want to change; updated_at is set automatically. The {uuid} must be a valid contact UUID, otherwise the API returns 400 with Invalid UUID.

curl -X PATCH "$BASE_URL/v1/contacts/{contact_uuid}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary mobile",
    "notify": 1
  }'

Response (200): the updated fields.

Two convenience parameters are handled on update:

• optout: true sets optin to 0.
• invalid: true sets valid to 0.

Updating a contact that has a client triggers a contact_updated auto message.

Opt In and Opt Out

Opt-in status controls whether a contact receives messages. The dedicated endpoints are the clearest way to change it and also handle scheduled messages:

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

• Opt in sets both optin and notify to 1. If the contact has a client, an auto message can fire. Returns {"message": "Contact {uuid} opted-in"}.
• Opt out sets both optin and notify to 0, and cancels scheduled, unsent messages addressed to that value. Returns {"message": "Contact {uuid} opted-out"}.

The {uuid} path value accepts a contact UUID or a raw value (a phone number or email address). When you pass a value, every matching contact is updated (up to 100), which is useful for opting out a phone number that appears on more than one client.

You can also opt a contact out during a regular update by sending optout: true (see Update a Contact), but the opt-out endpoint is preferred because it also cancels pending messages.

Archive a Contact

PUT /v1/contacts/{uuid}/archive

Sets archived_at, removes the contact from default list results, and cancels scheduled, unsent messages addressed to that value. Archived contacts are retrievable with the archived=1 list filter.

Response (200):

{"message": "Contact {contact_uuid} archived"}

Restore a Contact

PUT /v1/contacts/{uuid}/restore

Clears both archived_at and deleted_at, returning the contact to active lists.

Response (200):

{"message": "Contact {contact_uuid} restored"}

Delete a Contact

DELETE /v1/contacts/{uuid}

Soft-deletes the contact by setting deleted_at and cancels scheduled, unsent messages addressed to that value. The record remains retrievable with the trashed=1 list filter and can be brought back with Restore. Returns 400 with Invalid UUID when the path value is not a UUID.

Response (204): no body.

FAQs

What is the difference between a client and a contact?

A client is the person. A contact is one way to reach that person: a channel plus a value, such as a mobile number for text or an email address for email. A client can have several contacts, and messages are sent 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. As a shortcut, sending an email address in the contact field sets the channel to email automatically; a value sent without a channel is treated as text.

What phone number format should I send?

Any common US format works. The value is normalized to E.164, so (555) 123-4567, 555-123-4567, and +15551234567 all store as +15551234567. If a number cannot be validated, it is stored as sent and marked valid: 0.

What is the difference between optin, notify, and valid?

optin records consent to receive messages. notify controls whether notifications are sent to the contact. valid reflects whether the value is deliverable (a valid phone number or email address). A contact receives messages only when it is opted in, set to notify, and valid. Opting a contact out sets both optin and notify to 0.

How do I opt a contact out?

Call PUT /v1/contacts/{uuid}/optout, which sets optin and notify to 0 and cancels the contact's scheduled, unsent messages. You can pass a contact UUID or a raw phone number or email address; passing a value opts out every matching contact. Opting out during a regular update with optout: true is also supported but does not cancel pending messages.

How do I set or change a contact's label?

Set the name field on create, or send PATCH /v1/contacts/{uuid} with a new name. It is a free-text label (Mobile, Work, Home email) and does not affect delivery.

How do I list all contacts for one client?

GET /v1/contacts?client={client_uuid}. client_reference is also accepted in place of the UUID. Add channel, optin=1, or valid=1 to narrow the results.

Why did creating a contact return a 409?

The same value and channel already exist on an active contact (scoped to the client when a client is provided). Look up the existing contact instead of creating a duplicate, or restore it if it was archived or deleted.

Can I look up a contact by phone number or email instead of UUID?

Yes. GET /v1/contacts/{value} accepts a phone number or email address in place of the UUID and matches on the stored value. You can also filter the list with GET /v1/contacts?value={value}.

What is the difference between deleting and archiving a contact?

Both remove the contact from default lists and cancel its scheduled, unsent messages. Archiving (PUT /v1/contacts/{uuid}/archive) suits contacts that are inactive but worth keeping; they remain available with archived=1. Deleting (DELETE /v1/contacts/{uuid}) is a soft delete for records that should not exist; they remain available with trashed=1. Either can be undone with PUT /v1/contacts/{uuid}/restore.

Related Documentation

• API Reference: all resources on one page
• Payments: payment records and reminders
• Common Concepts: clients, contacts, and how records relate
• Rate Limits: request budgets for batch operations
• Error Handling: status codes and error responses