Video Overview

What is eCourtDate?

eCourtDate is an omni-channel communication platform used by justice and government agencies. Agencies can automatically send and receive two-way messages via texts (SMS), email, and voice calls.

Our API allows developers to integrate eCourtDate's scheduling and messaging capabilities into their own applications and workflows.

eCourtDate Agency Required

API Documentation

API documentation is available at docs.ecourtdate.com. The documentation provides information on the available resources, endpoints, and parameters, as well as examples of API requests and responses.

API Regions

We use multiple regions to provide a scalable, fast service for all of our users.

Staging Region:

Testing environment where outbound messages, data reporting, and payment processing are simulated.

API Base URL: https://staging.api.ecourtdate.com

Application URL: https://staging.ecourtdate.com

Production Regions (recommended for single-region users):

• https://us-east.api.ecourtdate.com
• https://us-west.api.ecourtdate.com
• https://us-south.api.ecourtdate.com
• https://us-texas.api.ecourtdate.com

Multi-region Production URL (supports all production regions):

API Base URL: https://api.ecourtdate.com

Application URL: https://app.ecourtdate.com

eCourtDate Console

The eCourtDate Console is where you can manage all agencies and API clients. You will need at least two clients - one for production and one for staging.

An API Client is used to authenticate API requests using an oAuth2-based Client Credentials grant.

Once signed into the Console, click on the APIs page to follow these steps:

Step 1 - Create an API Client

In the Console APIs page, click on Add API, then fill in the form to add a new API Client.

Step 2 - Configure the API Client

Single Agency configure the Default Agency. You do not need to enable additional agencies or send the agency in your requests.

Multi Agency configure both the Default Agency and Additional Enabled Agencies. You will need to send either the agency UUID or the agency reference in each request. If the additional agency is not found, then the default agency is used.

Step 3 - Request an Access Token

Copy the ACCESS TOKEN URL Client ID and Client Secret from the configured API client and request an Access Token.

Example CURL Request to Generate Access Token

    curl -X POST https://staging.api.ecourtdate.com/oauth/token \
    -H "Content-Type: application/json" \
    -d '{
      "client_id": "{client_id_value}",
      "client_secret": "{client_secret_value}",
      "grant_type": "client_credentials"
    }'
    

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

Example Postman Authorization Settings to Generate an Access Token

Authentication

All subsequent API requests must include the Bearer Access Token in the Authorization header. Example:

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

Step 4 - Verify Access to Agency

To verify access to an agency, use the GET /settings endpoint. Example:

Example CURL Request to Get Agency Settings

    curl -X GET https://staging.api.ecourtdate.com/v1/settings \
    -H "Authorization: Bearer {access_token_value}" \
    -H "Content-Type: application/json"
    

Step 5 - (Optional) How to Use Multiple Agencies

If you want to use more than one agency with the same API client, use an agency or agency_reference param

Example CURL Request to Get Agency Settings

    curl -X GET "https://staging.api.ecourtdate.com/v1/settings?agency_reference=demo" \
    -H "Authorization: Bearer {access_token_value}" \
    -H "Content-Type: application/json"
    

You can find the agency UUID and reference in the Console under Agencies. You can change the reference through the Admin > Settings page for the agency.

You can use the same API client for multiple agencies in the same region. You can't use the same API client in staging and production.

Example Postman Request to Get Agency Settings

Step 6 - Send Requests to the API

You can use the API to send messages, schedule events, and more. The API documentation provides information on the available resources, endpoints, and parameters, as well as examples of API requests and responses.

Example CURL Request to Send a One-off Message

    curl -X POST https://staging.api.ecourtdate.com/v1/messages/oneoffs \
    -H "Authorization: Bearer {access_token_value}" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "1234567890",
      "subject": "You have a Message from [AgencyName]",
      "content": "Your message content here",
    }'
    

Phone numbers and email addresses are accepted for the to field. You do not need to use a specific format.

    {
    "uuid": "message_uuid",
    "from": "agency_phone_or_email",
    "to": "recipient_phone_or_email",
    "subject": "Your message subject",
    "content": "Your message content",
    "last_status": "scheduled",
    "sent": 0,
    "mms": 0,
    "scheduled_at": "YYYY-MM-DD HH:MM:SS"
    }
    

Example Postman Request to Send a One-off Message

How to Include Message Metadata

You can provide metadata to track messages in your own systems. This is useful for reporting and analytics.

The following fields are available to include in the message metadata:

• type - The type of message
• event - The event UUID or reference
• case - The case UUID or reference
• form - The form UUID or reference

If you are not using other eCourtDate features, then the following fields are available:

• client - The client UUID or reference
• payment - The payment UUID or reference
• event - The event UUID or reference

How to Track Message Opens and Delivery Statuses

You can track when a message is opened by sending a GET /opens?message={message_uuid} request.

The last_open field in the message object is updated with the date and time of the last open.

You can track the history of delivery statuses by sending a GET /messages/{message_uuid}/metas request.

The last_status field in the message object is updated with the delivery status.

You can configure Webhooks to receive real-time data for inbound and outbound messages in the Console > Webhooks page.

How to Retry Failed API Requests

API requests can fail for a variety of reasons. We recommend a retry strategy with exponential backoff or setting a maximum number of retries.

The following status codes are common reasons why you might need to retry a request.

409 Conflict

The duplicate check prevents the same message from being sent multiple times within a 30-minute +/– window. If you intend to bypass the duplicate check, you can:

• Use the skip_duplicate = true parameter when using the /messages or /messages/oneoffs endpoints
• Set a scheduled_at date and time that is greater than 30 minutes from the previous message scheduled_at
• Use the duplicate_buffer and duplicate_interval parameters to control the duplicate time window (defaults to 30 minutes before and after scheduled_at)
• Wait until after 30 minutes from the scheduled_at date and time and send the request again
• Ensure that the message content is always unique

429 Too Many Requests

You have reached the rate limit for your account. Please wait at least 1 minute before retrying the request.

If you are on a Dedicated plan, configure the Allowed IPs setting, and email help@ecourtdate.com to increase the rate limit.

503 Service Unavailable

The API is currently unavailable. Please wait at least 1 minute and try again.

504 Gateway Timeout

The request could not be completed. Please wait at least 1 minute and try again. This is usually due to a temporary network issue.

If you experience a 503 or 504 error, please email help@ecourtdate.com with the details of the request.

How to Schedule When Messages are Sent

When using the /messages/oneoffs endpoint, you can set the scheduled_at parameter to the date and time that the message should be sent. Combine with the timezone parameter to specify the timezone of the date and time.

Example CURL Request to Schedule a One-off Message

    curl -X POST https://staging.api.ecourtdate.com/v1/messages/oneoffs \
    -H "Authorization: Bearer {access_token_value}" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "1234567890",
      "subject": "You have a Message from [AgencyName]",
      "content": "Your message content here",
      "scheduled_at": "2027-01-01 09:00:00",
      "timezone": "America/New_York"
    }'
    
  

How to Send Messages Immediately

Newly created messages are added to an automated queue to ensure messages are sent within carrier limits. If the message is scheduled to be sent immediately, there may still be a delay of up to 60 seconds before the message is sent.

To send a message immediately and bypass the queue, set the send_now parameter to true.

In addition, ensure that the following settings are configured under the Admin > Settings page for the agency:

Default Message Delay - set this to 0

Send Immediately - enable this checkbox

Click the Save button to apply any changes in the Admin > Settings page.

You do not need to set the scheduled_at parameter when sending a message immediately.

How to Resend Failed Messages

Messages are automatically retried by eCourtDate. You are not required to resend failed messages.

Common reasons why messages fail that are retried automatically:

• Temporary network issues
• Temporary spam blocks
• Volume limits reached
• Carrier or gateway issues

Messages are not automatically resent past 24 hours from the original send date and time. If the message is linked to an event, then the message is not resent if the event date and time has passed.

In the event of carrier or gateway issues that are due to an outage, retries are attempted once the issue is resolved.

To receive notifications when messages are automatically resent, use the General Settings > Issues Emails setting.

You can view carrier campaign status in Billing > Campaigns.

To learn more about carrier registration and best practices, see ecourtdate.com/carrier-registration.

To monitor message delivery and engagement, use the Reports and Data Dashboards.

If failures are due to out of service contacts, enable the Auto Run Lookups setting. This will automatically validate contacts prior to sending. If a landline is detected, the message is switched to a voice call.

Click here to view message Error Codes and Error Descriptions.

The JSON files are updated periodically to include new error codes and descriptions. You can integrate these files into your own systems to provide more detailed error messages to your users.

How to Check API Logs

You can view request and response logs in the Console under Logs.

You can filter logs by request data, request method, URL, IP address, User Agent, and more.

Troubleshooting

400 Bad Request

Ensure that the request body is valid and that all required parameters are included

401 Unauthorized

Ensure that you set the Authorization Header with the Bearer Access Token

Ensure that the API client is not revoked

403 Forbidden Agency is Inactive

Ensure that the agency is active

403 Permission Denied

Ensure that you are using an API client and not a user token

404 Agency Not Found

Ensure that you have a Default Agency configured

404 Not Found

Ensure that the API endpoint is correct

405 Method Not Allowed

Ensure that you are using the correct HTTP method

500 API Error

Check the API documentation for the correct request body and parameters.

API Support

If you have any questions or issues while using eCourtDate's API, please email help@ecourtdate.com.

To expedite resolving your support request, include a screenshot that shows the following:

• API Endpoint with any parameters
• Request Body
• Response Body
• Response Status Code

Do not share any sensitive information such as API secrets or access tokens in your screenshots.

We appreciate any feedback or suggestions to improve our API and developer resources.