LeanLaw's developer platform - including our APIs - are a core part of our mission to empower professional services firms to modernize and build better businesses. Our APIs are designed to enable teams of any shape or size to build robust integrations that help them customize and get the most value out of LeanLaw.

This article is an introduction to LeanLaw's API. We'll cover what the API does, and how to access and use it. Click here to jump ahead to instructions.

How does the API work?

An API (application programming interface) is a set of rules that allows two programs to securely communicate with each other to efficiently transfer data. If you wanted to copy your client and matter information into another program without an API key, you might have to individually reference and enter every line of your client and matter information by hand. By using your API key with a compatible program, your API key gives LeanLaw permission to tell the receiving program, “These entries are the clients’ names, these are their phone numbers, these entries are the matters,” etc.

API keys can save you days of data entry.

How secure is an API key?

The API key is called a key because it essentially unlocks specific data from your LeanLaw to the program with which you shared the key. However, your API key is far more secure than any physical key. Your API key is a 30 digit, randomized, unique code that can be deleted by you at any time. Once you delete the key from your firm’s API page, our database will never let it be used to access your data again--even from a program that was previously allowed access. It’s a very secure way of transferring data.

Exactly what data can other services access with my API key?

Right now, the following data can be accessed ('pulled from') with a LeanLaw API key:

All information from your Client Information page, such as names, phone numbers, and addresses.
- You can access all clients in one call, or you can specify one client and obtain all of their associated information.
All information from your Matter Info page, such as names, ID numbers, and practice areas.
- You can access all matters in one call, or you can specify one client and matter and obtain all of that associated information.
All responsible and originating attorneys connected to matters--but not their rates.

The following data can be added to ('pushed to') LeanLaw with a LeanLaw API key:

Create Clients and Matters
Create, modify, or delete Time Entries

That's what LeanLaw API keys currently "unlock."

Who can see my firm's API keys?

API keys are created, and visible, only from the API page in your firm settings. The only users who create or view API keys in your firm are users with the “Access to Firm Setup” permission, which can be enabled or disabled from your firm’s Users settings page. Note that whenever you or anyone else creates an API key, you and all other users with the Access to Firm Setup permission will be able to view and use the key until it’s deleted.

How to use LeanLaw's API: Getting started

Here we'll cover how to:

generate an API key in your firm's settings
use that key to authenticate and use with LeanLaw's GraphQL API
pass queries on our API Explorer.

We've also provided a quick video demonstration of our public API:

Table of Contents:

How to Generate an API Key

API keys are associated with the firm and not to a single user. You need an API key in order to authenticate a service with LeanLaw and access your firm's data. For security reasons, you should never share your key with anyone.

1. Go to Settings

Go to your firm's Settings page by clicking the gear icon ⚙️ in the top right corner of your page.

2. Go to API

In your firm's Settings page, click on API underneath the Integrations heading.

3. Click Generate API Key

In the API page of your firm's Settings, click the green Generate API Key button. This will give you the option to name your new API key as well as designate what access you will grant your API key.

4. Name your API Key and Save

Give a name to your API key. This name can be anything you'd like, such as the name of the user who's creating the key or the service it's intended for.

You now have an API key you can use for authentication. Note the Copy to Clipboard button provided for easily transferring your key. To test your key, continue by authenticating with the API Explorer.n

How to authenticate with the API Explorer

The API Explorer is a site we created to let you view the schema--the list of queries you can use with our API key--and use them in a test environment. You can visit the API explorer at https://graph.myleanlaw.co/graphql or by clicking API Explorer link in the API page of your firm's Settings.

In order to get any data from your requests, you need to authenticate with your API key. In the API Explorer, this is done in the HTTP header.

1. Click Operation Settings to open the HTTP header

In the API Explorer, open your HTTP header by clicking the 'HTTP Headers', indicated in the picture below.

2. Set up your API Key

In the HTTP header, enter this value as the "Name":

x-leanlaw-apikey

In the HTTP header, paste your API Key (copied from the LeanLaw Settings page) into the Value. It should look like the entry below, with your API Key in place of the 9s:

Name: x-leanlaw-apikey 
Value: "99999999-9999-9999-9999-999999999999"

The API Explorer is now authenticated with your API key, and you're ready to start entering queries.

Testing your API key

The following is a simple test you can run to make sure your API key is working, and get acquainted with the API explorer. Typing (or copying from below) the following query should retrieve a list of your firm's matter names and their universally unique identifiers (UUIDs).

query {
  matters {
    items {
      id 
      name
    }
  }
}

Note: Copying the above text may not copy the line breaks. Line breaks aren't mandatory; they're just for organization. However, proper spacing and capitalization are mandatory.

Query tools: Schema and autocomplete

The Explorer provides two valuable tools for finding compatible GraphQL requests, the Schema and control + spacebar suggestions.

API Schema

In the API Explorer, towards the top, click "Schema Reference".

The schema reference lists all query requests recognized by our API. It also indicates the compatible nesting order of requests. For example, if you open schema and see Clients, you'll see what can be nested inside Clients. In this new tab, you'll see Items; if you click on Items, you'll see what can be nested inside Items, and so forth.

Using the Schema, you can determine proper request and request ordering to make requests like:

query {
  clients {
    items {
      name 
      contact { 
        firstName 
        lastName 
        email
      }
    }
  }
}

This would request a list of all your clients' (company) names as well as the first name, last name, and email from their contact information.

Autocomplete (Control + Spacebar)

The API Explorer also offers autocomplete suggestions. If you hold 'control' and press spacebar while you're typing in the console, API Explorer will drop down a list of viable requests. The below screenshot demonstrates how the autocomplete can be used to discover viable requests--note how you'll still need to enter spaces and braces.

Getting more results

LeanLaw's API paginates search results with a limit of 1000 lines per page. Because of this, some requests may retrieve too much data to fit in the API Explorer. The tools listed in this section will help you check if you have more data than is being displayed, skip or take specific data, and sort your search results.

Using pageInfo{hasNextPage to check if more data is available

Adding pageInfo{hasNextPage into an item request asks the system if your request has another page of results that didn't fit in the page. If there is another page, this property will return "True" in your results. If there isn't another page, this property will return "False."

query { 
  clients { 
    items { 
      name
    } 
    pageInfo { 
      hasNextPage
    }
  }
}

The above request will retrieve all available client names and then answer the pageInfo query, informing you whether or not the results have another page you can't see.

Iterating searches with take and skip

If you have more data than you can fit on a single page, the arguments skip and take will be useful to you. Skip x tells the API not to retrieve the next x number of results. Skip and take are used in parentheses immediately following a property, before that property's brace, as demonstrated below:

query {
  clients(skip: 10, take: 5) {
    items {
      name
    }
  }
}

The above query will skip results 0-10 and take only the next 5 after that, retrieving results 11-15. By using one or both of these properties, you can skip through the 1000 results you've already seen or limit your results for a certain search so you're able to fit other data on a page.

Sorting data with ASC and DESC

ASC (ascending) and DESC (descending) can be used to rearrange data in the order that matters to you. They must be used inside braces following the order command, and the order command must be within parentheses. For example:

query { 
  matters(order: {
    name: ASC 
    reference: DESC
  }) {
    items {
      name 
      reference
    }
  }
}

As you can see, multiple ordering properties can be applied to the same results. In the above example, a query is retrieved for all matters by name and reference (matter ID); the matters are sorted first in ascending order by name and, in the event that any matter names are duplicated, those duplicates will be sorted in descending order by reference.

More code samples

curl

The following snippet shows the curl command to fetch a list of clients from the API:

>curl \
> -H "x-leanlaw-apikey: <leanlaw-apikey>" \
> -H "Content-Type: application/json" \
> -d "{\"query\": \"{clients{items{id,name}}}\"}" \
> https://graph.myleanlaw.co/graphql

Nodejs

The following snippet fetches a list of clients from the API.

const fetch = require('node-fetch');

const query = `{
  clients {
    items {
      id
      name
    }
  }
}`;

fetch('https://graph.myleanlaw.co/graphql', {
method: 'POST',
body: JSON.stringify({ query }),
headers: {
'Content-Type': 'application/json',
'x-leanlaw-apikey': process.env.LEANLAW_APIKEY
}
})
.then(res => res.json())
.then(json => {
// process results
console.log(JSON.stringify(json));
})
.catch (err => {
console.log(err)
});

Save to file, install, node-fetch module and include the API key in your environment
npm install node-fetch@2.6.1 export LEANLAW_APIKEY=xxx