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 functional 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.

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 as shown below.

Open

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 is 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 setup 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.

Open

After authorizing, you will be returned to the Developer page where it should show you a success that looks like this:

Open

Now, you will be able to execute calls on the Developer page as the appropriate authentication headers are in place.  Let's take a look at what those look like.

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 d6d69419-6666-9999-aa54-f4f8f421f38e

That token is called an Access Token.  Depending on how you are provisioned, they can be set to expire in 30 to 365 days.  For security purposes, they never last forever.

You may also be provisioned to get a Refresh Token if you prefer that OAuth2 workflow.  The explanation is a bit outside the scope of this document.  But the basic gist is that a refresh token is a token that lets you get more access tokens.

Testing

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