Getting started

The API follows industry norms around JSON-based REST APIs. The details on the endpoints and request and response formats can be found under API Documentation. But we recommend walking through this document first for basic information about authentication and other topics.

Also check our a brief walk-through of LeanLaw Concepts that contains helpful background information to navigate the API.

Authentication

All API endpoints are authenticated by passing in a bearer token on the header with a LeanLaw API key.

Authorization: Bearer {apikey}

To obtain a key, log into your LeanLaw account and create it like this:

  • Go to Settings > API and click "Generate API Key"

  • Pick permissions (scopes) for the key (read or write), give it a name and click "Save"

  • Copy the key (it will only be available once) and store it in a safe location

The API key represents the FIRM and acts on behalf of it with the access provided by the scopes associated with the API key when it was created. Many use cases for the API requires identifying a user. Those API calls have a `userId` filter or parameter, but as an alternative the user information can be provided in as a header value for all calls:

x-leanlaw-userid: {userId}

This is the recommended approach for time tracking use cases where lists of matters and lists of time entries are for a specific user. The `userId` can be received from the `ListUsers` endpoint, either by listing all users or querying users by email.

What to Try First

Get a simple API request working first. For example, start with a curl request from the command line:

$ export APIKEY=...
$ curl -H "Authorization: Bearer $APIKEY" https://api.leanlaw.io/v2/users

This should return a blob of JSON with a list of users.

Alternatively, go to the API Documentation and try some requests from there. Remember to add the authorization header value.

A great way to get familiar with the API is to download the OpenAPI spec into PostMan:

  • Go to the API Documentation page click "Download definition" and pick "Open API 3" (YAML or JSON)

  • In PostMan, click import and upload the file that you downloaded in the first step

  • In the imported collection go to the "Auth" tab, pick the "Bearer Token" auth type and enter your api key as the token

Partner ID

If you are a LeanLaw partner provide your id on all requests in the header as follows:

x-leanlaw-partnerid: {id}

General Patterns

  • All requests and responses are formatted as JSON

  • Updating objects (with PUT) use "sparse" update semantics (only properties that are provided in the request will be changed)

  • All responses are wrapped in a standard JSON object, with the return object or lists of objects in the data property

    { "data": { "id": 123, "name": "tim" } }

  • GET, PUT, and DELETE requests return a 200 status code if successful

  • POST requests return 201 status code if successful

  • Most endpoints that return lists of objects are paginated. The maximum number of items returned in a request is 1,000. Pagination is controlled by the query parameters limit (number of items returned) and offset (starting index of item). The returned list will contain a pagination property containing the total number of items. In this example, 1,000 items are returned but there are 1,543 more:

    { "data": [...], "pagination": { "limit": 1000, "offset": 0, "total": 2543 }}

Standard Error Responses

  • 401 - missing authentication (no API key provided)

  • 403 - the token is not authorized to performance the action or is invalid

  • 429 - throttling. The caller has issued to many requests. Initiate a backup retry strategy

  • 400 - invalid request (bad parameters or invalid request data)

  • 500 - server-side error. Please notify us if this happens

All responses contain a trace id in the header that is helpful if you need help understand why a request is not working as intended or causing an error:

x-leanlaw-traceid: {id}