Core APIs

LegalServer Core APIs

LegalServer's Core APIs are where all of our ongoing development is taking place. APIs are being restructured to make more use of consistent field names, schemas, and internal frameworks. They also use a Universally Unique Identifier (UUID) to track objects within LegalServer. Also, unlike with the Legacy APIs, the Core APIs are much more restrictive on the verbs used in the API calls. We've built a more cohesive framework for our modern APIs.

v1 APIs are now at a stable place and will not receive much in the way of new functionality, although new endpoints will be released using the existing framework.

v2 APIs are in active development and enabled everywhere.

v3 APIs are in active development and not yet available.

Some of our Core APIs require an additional paid subscription while others are available broadly. APIs requiring a subscription are referred to as our Premium APIs.

The Core API endpoints that are not Search or Create operations typically require the UUID in the path. This includes a GET Specific Record, PATCH Specific Record, and in very limited cases DELETE Specific Record.

Core APIs can accept data formatted in two different ways. It can be in a JSON format or it can be URL Encoded (for search only). Our documentation is presented as JSON formatting only.

When Core APIs return multiple records, they are always ordered by the ID value ascending unless the sort  parameter is set.

Included APIs

Many of LegalServer's APIs are available out of the box. These include the APIs to:

• Create/Update Contacts
• Create/Update Lookups
• Create/Update Organizations
• Create/Update Users
• Create Documents on Cases
• Create Case Notes

And all of the Core APIs to read or search data are available.

All the included APIs are identified in an OpenAPI schema whose filename includes .Included .

Premium APIs

These APIs require LegalServer Support to enable them for organizational use. Unlike the Legacy APIs or some other endpoints, they are not included in the base LegalServer subscriptions. The current cost is $200/month. Please reach out to support@legalserver.org to request a change order to enable on your site. If they are not currently enabled, you will receive a 402 error indicating that Payment is Requested to enable.

Our API documentation has two version of v1 and v2 documentation. The Premium versions include documentation for all endpoints in that version. The Included versions include just the free and included endpoints.

Premium APIs currently include the following endpoints:

• Create/Update Matters
• Create SharePoint Folder for Matters
• Create/Update Adverse Party records on Matters
• Create/Update Assignment records on Matters
• Create/Update Charge records on Matters
• Create/Update Contact records on Matters
• Create/Update Income records on Matters
• Create/Update Litigation records on Matters
• Create/Update Non-Adverse Party records on Matters
• Update Notes records on Matters (Creating Notes is free)
• Create/Update Events
• Create/Update Event Reminders
• Create/Update Tasks/Deadlines
• Conflict Checks

The ability to get back details about a case or search for cases is available outside of the Premium API. The full details returned will include Assignment, Charge, Income, Litigation, and Service records, but it will not include optional custom fields unless specified.

Some examples of where this could be used:

• Creating new cases from a third party system,
• Creating Prescreens from a screening system,
• Updating service records tracking communications with the client,
• Indicating a case was placed with a volunteer or other assignment,
• Checking to see if there is a potential conflict before making a referral.
• Creating Service records on Matters to track USCIS filing reciepts

Core Matters APIs

These APIs are focused around the Matter record. Create and Patch APIs on the Matter are typically Premium APIs with one exception. There are four basic endpoints:

• Search for a Matter (Generally available and not restricted for just the Premium API)
• Get a Matter (Generally available and not restricted for just the Premium API)
• Create a Matter (Premium)
• Update a Matter (Premium)

The search functionality can return the data in multiple ways. It can be a full data result or it can be more in line with the Legacy Pro Bono Opportunities or Caller ID APIs.

There are a number of additional API endpoints that are related to these including endpoints for Assignments, Services, Litigations, Charges, Contacts, Notes, and SharePoint on the matter record. All of the active uses of these endpoints (Create, Update, and Delete) are Premium APIs.

Since Events and Notes can be both very verbose and full of attorney/client confidential data, that data is not included in the responses by default. It can be included when the specific user role permission is included.

Conflict Check API

This API is part of our Premium APIs, however it is not configured by default when turning on access to Premium APIs. Please open a ticket or email Support to have it configured and enabled if you have the Premium APIs.

Core Users APIs

These APIs are focused around the User record. There is no charge for these APIs. There are four basic ones:

• Create a User
• Update a User
• Get a User
• Search for a User

When utilizing these APIs, LegalServer will automatically create a UUID for the user and that is the key needed for additional API calls. If you are integrating from an external system that has created its own UUIDs, or you want to match based on Bar Number or some other unique number/string, you can utilize the external_unique_id  field to store that information. You will still need to use the LegalServer Search for a User API to convert your external_unique_id  into a user_uuid , but the functionality is supported.

This set of APIs also includes endpoints to manipulate the User's subjects and create User notes.

Core Lookup APIs

These are APIs that are focused on different lookups within LegalServer. There is no charge for these APIs. Depending on the Lookup they allow for reading, adding, or updating the data present. If there are additional lookups that would be helpful for API access, please reach out to support@legalserver.org with details.

Core APIs and GIS

Updating an address will result in geocoding if the site has GIS enabled. Any relevant GIS fields will be returned with the Client's home address.

External IDs and Aligning Data

APIs allow for the alignment of data between LegalServer and an external source. external_id  parameters exist on Events, Matters, Matter Charges, Matter Services, Matter Litigations, and the Charge Lookup. These fields are available to interact with via the API but are read-only in the User Interface. These fields are designed to allow for the alignment of data in integration projects. These new fields often do have a unique constraint.

Users and Organization have a separate field named external_unique_id  which serve the same purpose and do have that unique constraint, but are editable in the User Interface.

v1 Core API Field Nuances

Organizations

In the Core API, when an Organization is referenced as a parameter, it will display like:

json "court_id": { "organization_id": 11, "organization_uuid": "UUID GOES HERE", "organization_name": "Blackacre County Court" }

To set or update that value, there are five acceptable options:

1. "court_id": 11
2. "court_id": {"uuid": "UUID GOES HERE" }
3. "court_id": {"id ": 11 }
4. "court_id": {"organization_uuid": "UUID GOES HERE" }
5. "court_id": {"organization_id ": 11 }

Our documentation will show the later two options so that the input matches the output. The other options are not documented in the specific API calls.

Users

In the Core API, when a User is referenced as a parameter, it will display like:

json "closed_by": { "user_id": 11, "user_uuid": "UUID GOES HERE", "user_name": "LegalServer Staff" }

To set or update that value, there are three acceptable options:

1. "closed_by": 11
2. "closed_by": {"user_uuid": "UUID GOES HERE" }
3. "closed_by": {"user_id ": 11 }

Core APIs and Nulls

To search for something that is null, you can use %empty%  in place of the word null . This only works as a lowercase parameter. Since Null could be interpreted as a string (especially in a GET Query Parameter), we use the special phrase instead. A blank parameter (i.e., office= ) will be ignored. To search for Users without an office, you'll have to use office=%empty%  instead.

%empty%  can also be used in POST or PATCH API calls to set a field's value back to null. This works with scalar fields, but will not work for fields that accept a json array.

v2 Core APIs

LegalServer's v2 Core APIs are in active development. They are available upon request, but are not enabled by default. There are several structural differences from the v1 endpoints including with multiselects, dates, and other functionality.

One key change is that Lookup values are not returned with just the text of the lookup value. Instead an object is returned that includes details about the lookup value (lookup_value_id , lookup_value_name , lookup_value_uuid ) and also details about the lookup table (lookup_type_name , lookup_type_table_name , lookup_type_custom , lookup_type_uuid ). For example:

json { "lookup_value_id": 881, "lookup_value_name": "Open", "lookup_value_uuid": "4fd0f756-69ec-4fb6-b5ba-2ab750124b75", "lookup_type_name": "Case Disposition", "lookup_type_table_name": "case_disposition", "lookup_type_custom": false, "lookup_type_uuid": null }

This means that if you want to discover other valid values for a lookup, you can make an API call to discover it. If it is not a custom lookup, you can use the /api/v2/lookups/{table_name}  endpoint to get the potential values. If it is a custom lookup, you will soon be able to use a new endpoint /api/v2/custom_lookups/{lookup_type_uuid}/lookups  to get the potential values.

These endpoints are also limited to a maximum of 100 results at a time. As these results are more verbose, the limit will be silently enforced if more results are requested.

v2 APIs currently default to v1 APIs responses and parameters unless/until the endpoints are modified for any v2 changes. Lookups will respond with the v2 objects however.

v2 Get Custom Fields

In the Search Matters and Get Matter Details endpoints, the v2 version allows for custom fields on subtables (Litigations, Charges, and Services) to be returned as part of the call. This is a departure from v1 where only custom fields on the matter are returned.

v2 API Permissions

v2 APIs adds a new user role permissions:

• API Access all Cases

These permissions are only needed on sites that have v2 APIs enabled. When using the Matter API endpoints, case restrictions for assigned users and exclusion from Search are now being honored by the API. This includes Office and Program restrictions, specific Case Restrictions or Exclusions, and Assignment Restrictions. If the API user does not have this new permission, they may be limited in not seeing cases that they would otherwise see. Note that the total_records  parameter in the Search Matter API  will return the number of all possible results, not the number of all results that meet the user's permissions. If a Get Specific Matter API call is made for a case where the exclusion is set, then the response will be a 403  error not allowing access.

v2 API Page Limits

v2 APIs will limit results to a maximum of 100 results to prevent timeouts and standardize server load. If more than 100 results are requested, only 100 results will be returned.

v2 API Custom Responses

Using the custom_results  parameter will allow you to control the results from a v2 API endpoint. This should be included in the body of a POST/PATCH call or in the query parameters of a GET/SEARCH call. By default, the responses are verbose. If you include "custom_results":[]  the only thing returned will be the relevant object UUID. If you were to specify specific fields or arrays in that endpoint by "custom_results":["first","last","assignments"]  then those fields/arrays will be displayed in addition to the UUID.

v2 Upsert Capabilities

Upsert allows for searching for a particular record and updating it. However, if that record is not found, it will automatically create a new record.

Upsert happens using a POST API call. In addition to the destination parameters, an additional parameter named update  is required. This parameter takes an object of all the search parameters that it should be looking for. These parameters need to be available in the appropriate Search endpoint to be used here.

If no records are found, then the POST request is processed as normal.

If one record is found, then the PATCH request is processed as normal and the PATCH permissions are checked.

If more than one record is found, an HTTP 400 response is returned with the message Cannot process multiple records for upsert .

For example, the following POST User API payload will either update a user record from John Doe  to Jane Doe  or create a new user named Jane Doe . Update parameters are copied to the POST request when they do not conflict with other parameters that are specified.

json { "update" { "first": "John", "last": "Doe" }, "first": "Jane" }

Upsert capabilities are currently limited to API v2 Contact, Event, Matter, and User endpoints.

Rate Limiting

LegalServer rate limits the User Interface at the standard rate of 200 requests per minute averaged over the last two minues. A similar rate limit has been implemented for the Core APIs generally. The current default limit is 200 requests per minute checked every ten seconds. Responses now include headers for x-rate-limit-limit , x-rate-limit-remaining  and x-rate-limit-reset . x-rate-limit-reset  returns the epoch time when the rate limit rests. Rate Limit errors will result in a Error 429 response of Too Many Requests .

Rate limit increases will be considered on a case-by-case basis. There may be an additional cost for the rate limit increases.