Download OpenAPI specification:Download
The Everlaw API is organized around REST. Our API has predictable resource-oriented URLS, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and methods.
The Everlaw API uses API keys to authenticate requests. You can view and manage keys for your organization on the Organization Admin page.
Your API keys grant access to your Everlaw platform data - be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, open S3 buckets, etc.
You should provide your API key as a Bearer token when making an API request by setting the "Authorization" header:
Authorization: Bearer everlaw-api.XXXX.YYYYYYYY
You must provide your API key with every request, and all API requests must be made over HTTPS.
All responses are in JSON format. Response entities are encapsulated in a JSON object along with any other top-level response content, e.g. pagination links (see the Pagination section below):
{
"data": {
"id": 1,
"name": "Test Project"
...
}
}
Some API endpoints fetch lists of objects (e.g. listing all users in an organization).
These list API endpoints share a common structure, taking at least these two parameters:
limit
and after
. The Everlaw API utilizes cursor-based pagination via the after
parameter.
This parameter takes an existing object ID value and returns objects starting after the given ID.
The limit
parameter specifies how many objects you would like to return in a given request.
Paginated responses will include a links
entry in the top-level response that provides pre-built
pagination links for fetching more results (if they exist). This links
object will always
include a next
key which is a URL to fetch the next page of results OR null
if this was the last
page of results:
{
"data": [{
"id": 1,
"name": "Test Project"
...
}],
"links": {
"next": "https://...."
}
}
The Everlaw API employs rate limiting to help limit the performance impact of API activity and
maintain stability. There is a fixed rate limit of 25 requests per second enforced per authenticating
user account. Request rates that exceed this limit may see error responses with status code 429
.
Additionally, there is a stricter rate limit enforced for failed authentication (invalid/missing
API tokens).
A basic approach for handling rate limiting is to watch for 429
status codes and employ a retry
mechanism. This retry mechanism should follow an exponential backoff schedule (with increasing
delays between successive retries) to reduce request rates when necessary.
When using the Everlaw API it is important to consider users that are interacting through the Everlaw platform - actions you take through the API (particularly those that create or modify platform objects, such as uploads/datasets) can impact the platform experience for your reviewers. To help keep this experience user-friendly and performant, Everlaw imposes some limits on how the API can be used, including the rate limits discussed above as well as operation-specific limits. These limits include caps on the number of user-visible objects created via the API (for example, a limit on the number of datasets that can be created via the API), and will be called out on the specific operations below.
If you hit one of these limits, the operation will fail with response code 422
(unprocessable) and
include an error message indicating the particular limit. These limits can be adjusted for specific
databases or organizations as necessary to allow for continued API use - please contact Everlaw Support
for more information or if you would like to adjust a particular limit.
The Everlaw API uses conventional HTTP response codes to indicate the success or failure of an
API request. In general, codes in the 2xx
range indicate success; codes in the 4xx
range
indicate an error with the request content (e.g. a missing parameter, or insufficient permissions);
codes in the 5xx
range indicate an error with our servers (e.g. scheduled maintenance).
Error responses will include a JSON body with a human-readable title indicating the cause of the error and the HTTP status code:
{
"title": "You do not have permission to make this request",
"status": 403
}
Users on Everlaw are typically members of one or more organizations. These organizations are a convenient way to group and manage user accounts as well as case data (databases and projects) owned by the organization. Each organization is associated with a list of members (some of whom may be "org admins") as well as a list of databases and their associated projects that the organization owns.
Organizations are administered by members that have been granted the "org admin" role, allowing them administrative control over membership, SAML/SSO configuration, access to organization-owned cases, management permissions over organization API keys, and other functionality. Organization-level API keys are also granted this "org admin" role. For more details, see Organization Administrator.
Matters on Everlaw are organized into top-level entities known as databases. Each database is a separate collection of documents owned and administered by a particular organization. Every database has one or more associated projects, which contain a subset (possibly all) of the documents in the database, but which have their own entirely separate review work. For more details, see Database and Project Permissions.
There are a few important actions possible at the database level - in particular, uploading and deleting documents and administering (creating/modifying/deleting) projects associated with the database. These are managed via permissions on the database objects. For more details, see Database Administration and Permissions.
At the project level, permissions are managed via User Groups, which comprise a set of permissions and a list of members granted those permissions. Users can be members of one or more groups, and are granted the union of all the permissions of those groups. For more details, see User Groups and Project Permissions.
Organization admins are by default granted administrative access to the databases owned by that organization (as well as all associated projects). It is possible to disable this org admin access for specific databases as necessary to limit org admin access; in that case, org admins will be able to fetch basic summary information about the database/projects (e.g. its name, total billable size, etc) but not access documents or other similar data. This distinction is reflected in the separation of "Database/Project Org Admin" endpoints from others at the database and project levels. For more details, see Organization Admin: Organization and Project Administration.
Matters on Everlaw are billed based on the amount of data hosted each month. There are several endpoints available to fetch billing information for a particular month by database or project or across an entire organization. This billing information includes sizes of the hosted data by data type (native, pre-processed, produced) and storage type (standard, ECA) as well as project/database status information relevant for billing - e.g. when a project was suspended or deleted.
Monthly billing information will include both final sizes and peak sizes. Final sizes reflect the size at the end of the month (or the current date, if the month has not yet ended), whereas peak sizes reflect the maximum size observed over the given month (which is the basis for computing your actual bill). Each size point includes sizes for Standard and ECA (Early Case Assessment) data, which are further broken down by data type.
Monthly billing information also includes status information that reflects the state of the project/database over the course of the month. This includes the effective state of the project for the sake of billing (i.e. do we consider the project to have been active/suspended/deleted for the month), the final/end-of-month state for the project, and timestamps for important state changes (e.g. suspension, deletion).
When requesting billing information for a database, our response will include separate billable size and state information for each project in that database, as well as a combined overall billable size and state for the database. The combined database size typically reflects the size of the largest project in that database, and the status is the merger of the status of all the projects (e.g. if any project is active, the database as a whole is considered active; if all projects are suspended, the database is considered suspended, etc).
List databases you have access to, either via explicit admin permission or as an org admin for its owning organization.
None.
after | integer The id of the element after which to start this page |
limit | integer [ 1 .. 200 ] Default: 100 Max records to return |
{- "data": [
- {
- "context": "EVERLAW",
- "id": 0,
- "name": "string",
- "orgAdminAccess": true,
}
],
}
Get user information for the account associated with the API key provided with the request.
None.
{- "data": {
- "firstName": "Jane",
- "id": 1,
- "lastName": "Doe",
- "organizations": [
- {
- "id": 0,
- "name": "Law Firm X",
- "orgAdmin": true
}
], - "primaryOrganization": 1,
- "title": "Attorney",
- "username": "jdoe",
- "email": "user@example.com",
- "joined": "2019-08-24T14:15:22Z",
- "lastLoggedOut": "2019-08-24T14:15:22Z",
- "mfaRequired": true
}
}
List all organizations that you have access to. This will always include all organizations the calling user is a member of.
None.
after | integer The id of the element after which to start this page |
limit | integer [ 1 .. 200 ] Default: 100 Max records to return |