API

Representational State Transfer (REST) Application Programming Interfaces (APIs) are the way to go when you want to integrate systems. They allow for a stateless transfer of information. We have exposed some of our most used functionality through our APIs now so that external systems can use them to do fun things like create hearings and cover appearances. We look forward to working with partners to integrate this functionality into their practice management software, scheduling systems, and more!

We have an API explorer that provides in-depth documentation and the ability to exercise the APIs at:

https://docketly.com/developer/

Authentication

We offer 2 different methods of authentication for your REST requests. You can experiment and see them in action from the Developer page linked above.

HTTP Basic

We support HTTP's BASIC authentication on all requests. You can use your same username and password as you do for the website. You may want to set up an additional "dummy user" that you use for access to the APIs. This is the fastest way to get going. However, passwords must be changed per our password policy. You may do that and unknowingly break your integration because you hard-coded a password that needs to be updated.

There are plenty of resources on the internet to describe how BASIC authentication works. But the quick explanation is that you will take your username and password for our website and concatenate them separated by a colon. The value might look like "brandon@yahoo.com:mybestpasswordhere". Then this value is base64 encoded. This value is sent as an HTTP header in your request. The header would look like:

Authorization: Basic YnJhbmRvbkBBBBBc2pmOmFqZHNmbGthc2RqbGY=

OAuth2

OAuth version 2 is an industry-standard way of granting permissions with tokens to a different application to act on your behalf. This is the preferred way to work with our API in production over the long term. Experiment with Basic, but deploy with OAuth2.

App Page vs. Access Token — What's the difference?
Your Developer App page shows your client_id and client_secret. These are your app's registration credentials — they identify your app and are used to start the OAuth2 flow. They are not your Access Token. The Access Token is generated separately by completing the authorization flow described below.

Visit our Developer App page to get started. You will be given back a client_id and client_secret. These 2 pieces of info are needed to get you through the first hurdle but they are insufficient alone to authenticate. There is more to do. Here we will demonstrate using the Developer page as it may help give some visualization to that call flow.

By clicking on Authorize on the Developer page, you see the authorization methods. Scroll down to the OAuth2 section. The items listed under "Authorization:", "Token URL", and "Flow:" will come in handy if you are coding this yourself. The Developer page is merely showing you what it is pre-programmed to use.

Enter your client_id and client_secret in the boxes as shown.

You will want to check the appropriate boxes of the scopes that you will be using. OAuth2 attempts to be granular so tokens can get given to different parties with specific data in mind. When your client_id was set up, a set of scopes was created for you. You may only choose from this set. The usual mistake is trying to select a scope that is not applicable to your user role such as a client trying to add "reports:write". That's an attorney-centric scope.

Once complete, press the Authorize button. The screen will open a new browser tab that will take you to Docketly to login. You will then be shown a dialog where you will grant permission for the scopes you want this token to have access to on your behalf.

After authorizing, you will be returned to the Developer page where it should show you a success. Now, you will be able to execute calls on the Developer page as the appropriate authentication headers are in place.

Much like the HTTP Basic request, you will give an Authorization header. This time we will use the prefix Bearer with the token following it.

Authorization: Bearer a1b2c3d4-e5f6-7890-abcd-ef1234567890

That token is called an Access Token. Depending on how you are provisioned, they can be set to expire in 30 to 365 days. Your expiration period is reflected in the expires_in field (in seconds) of your token response. If you are unsure of your provisioned period, contact support@docketly.com.

Capturing Your Access Token

Important: Save Your Token When It's Issued
The Access Token is returned only once — in the JSON response body when you complete the authorization code exchange. It is never displayed again in the app or UI after that point. You must copy and store it securely at the time it is issued.

Your response will look like this:

{
  "access_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "token_type": "bearer",
  "refresh_token": "98765432-fedc-ba09-8765-43210fedcba9",
  "expires_in": 31536000,
  "scope": "hearings:read coverage:write ..."
}

Store both the access_token and refresh_token values — you will need them.

Using Your Refresh Token

If you were provisioned with a Refresh Token (check your authorization response — if refresh_token appears in the JSON, you have one), you can use it to obtain a new Access Token without re-running the full authorization flow. This is especially useful when your Access Token expires.

Make the following request:

POST https://docketly.com/api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<your_refresh_token>
&client_id=<your_client_id>
&client_secret=<your_client_secret>

The response will be a new Access Token JSON, identical in format to your original authorization response. Store the new values — the previous token is now invalid.

Lost or Expired Token?

If your Access Token expired but you have a valid Refresh Token: Use the refresh flow above — no action needed on our end.
If both are expired or unavailable: Simply re-run the full authorization flow. Navigate to https://docketly.com/oauth2/authorize with your client_id, redirect_uri, and desired scopes. A new Access Token and Refresh Token will be issued. Nothing needs to be reset on our end.
If you're stuck: Contact support@docketly.com and we can help troubleshoot.

Testing

If you are interested in using this capability, let us know. We can get you access to it and test servers.