LeanLaw Concepts
This page discusses some specific concepts in LeanLaw that are helpful to understand to use the API effectively.
Clients and Matters
Most things in LeanLaw revolve around clients and matters.
-
All matters are associated with exactly one client (and by extension, a client have zero or more matters)
-
All matters have exactly one responsible user assigned
-
One or more users are assigned to a matter. In some firms, all users are assigned to all matters, but in some cases users are only assigned to the ones they are working on.
Law firms may have ids associated with clients and/or matters that they use to identify them. These ids are referred to in the API as "reference". In LeanLaw's UI, they are called "Client ID" or "Matter ID". This should not be confused with the internal GUIDs used for all resources in the API. For example, here is JSON representing a matter in the system
Code
The internal LeanLaw ids (GUIDs) that are used by the API are seen as the matterId and clientId in the JSON object.
The Matter ID as known by users of the firm is seen in the reference property as "25-0912".
In this case, the firm has a reference on the matter, but not on the client. In some firms, there are references on both, and in other firms on neither.
Billable Items
Billable items are one of the following types, each with their own set of endpoints in the system:
-
Time entries
-
Expenses
-
Fixed Fees
Some things to be aware of with billable items:
-
They are always assigned a date
-
They always have a description
-
They are associated with exactly one matter (and by extension, its client)
-
Time entries always has a user assigned; expenses and fixed fees optionally have a user
Custom Fields
Firms can define their own fields to track information that LeanLaw does not have a built-in property for, such as a referral source on a client or a case type on a matter.
Custom fields are configured by the firm inside LeanLaw. They cannot be created, renamed or deleted through the API, and the values on a record are currently read-only through the API as well.
There are two separate things to understand: the definition of a field, and the value a particular record holds for it.
-
A definition is the field as the firm configured it: its name, what kind of value it holds, and (for enum fields) the options that can be selected. ListCustomFields returns the definitions.
-
A value is what one specific client, matter or user holds for that field. Values are returned in a
customFieldsarray on the record itself.
The id property is what ties the two together: the id in a record's customFields array is the id of the definition it belongs to.
Which records can have custom fields
Each definition belongs to exactly one type of record, given by its entity property:
clientmatteruser
A definition only ever applies to its own entity type. A field defined for clients will never appear on a matter, even if the two have the same name. Firms may also configure custom fields on other things in LeanLaw (fixed fees, for example); those are not exposed through the API.
ListCustomFields returns the definitions for all entity types together, which is why each one tells you its entity. Pass entity on the query string to narrow it down, for example entity=matter.
Code
Value types
The valueType of a definition tells you what the value will look like on a record:
-
text- a string -
number- a JSON number, not a string -
enum- one option picked from a fixed list (see below) -
boolean-trueorfalse -
date- a date string inYYYY-MM-DDformat
Firms can currently only configure text, number and enum fields in LeanLaw. The boolean and date types are reserved for future use, but it is worth handling them so that your integration does not break if they start being used.
Reading values on a record
GetClient and GetMatter always include the customFields array. On list endpoints it is left out by default to keep responses small, and is included by adding select=customFields to the query string - this works on ListClients, ListMatters and ListUsers.
Code
Two things to be aware of when reading values:
-
Only fields that actually hold a value are returned. A field the record has nothing stored for is left out of the array rather than returned with an empty value, so an empty
customFieldsarray means no values are set, not that the firm has no custom fields. -
Because of that, do not use a record's
customFieldsto discover which fields a firm has configured - use ListCustomFields for that.
Enum fields
For an enum field, the value is the label of the selected option, so you can display it directly. The record also includes the optionId of that option.
Prefer the optionId over the label when you store or match a selection: labels can be renamed by the firm at any time, while the id stays the same for the life of the option. The full list of options a field allows is only available from ListCustomFields, so that is where to look if you need to show the choices rather than just the current selection.
Note that ListCustomFields returns the options that are currently available to choose from. If a firm retires an option, records that still hold it keep returning its label and optionId, so a record's current selection is not guaranteed to appear in that list.
The two built-in matter fields
Matters have two built-in custom fields that firms configure by giving them a name in LeanLaw's settings. They behave like any other text custom field, with one difference: instead of a GUID, their ids are the fixed strings custom1 and custom2.
These two only appear - in ListCustomFields and on matters - once the firm has given them a name. A firm that has not named them has no custom1 or custom2 field, and any values stored against them are ignored.