Everlaw API (1.alpha)

Download OpenAPI specification:Download

Introduction

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.

Authentication

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.

Response Format

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"
       ...
   }
}

Pagination

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://...."
   }
}

Rate Limiting

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.

Other Limits

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.

Errors

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
}

Data Model

Organizations

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.

Case Data

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.

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.

Billing

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).

Global

Global operations.

GetDatabases

List databases you have access to, either via explicit admin permission or as an org admin for its owning organization.

Required Permissions

None.

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetMe

Get user information for the account associated with the API key provided with the request.

Required Permissions

None.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetOrganizations

List all organizations that you have access to. This will always include all organizations the calling user is a member of.

Required Permissions

None.

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjects

List all projects you have access to

Required Permissions

None.

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

ApiStatus

Check the current API status. On success, returns success code 204 and no content.

Required Permissions

None.

Responses

Organization

Organization-level administrative operations.

PostCustodians

Syncs the people in a legal hold directory by uploading a csv file. Usage goes as curl -H "Authorization: Bearer everlaw-api.yoursecretkeyhere" -F "file=@path/to/custodian/file.csv" api.sandbox.everlaw.com/v1/directories/directory-id-number/custodians.

This sync will overwrite all values of existing people with an email in the provided csv file. If a property is not present for a person, that property will be empty after the update. People with a user principal name but no email will be ignored, and all ignored people will be reported in the response to the request.

Column names are changed to lowercase and matched against a list of properties. We currently support: "email" "business phone" "company name" "user principal name" "employee start date" "employee end date" "manager name" "manager email" "mobile phone" "role" "employee type" "department" "fax number" "office location" "other emails" "preferred language" "notes" "name" "first name" "middle name" "last name".

Ignored fields that will be supported at a later date: "employee id" "identities" "my site" "preferred data location"

The only supported date format is yyyy-MM-dd.

There are two ways of providing names to a person: by specifying the "name" property or by any of the name sub properties i.e. first/middle/last name. If any of the name sub properties are present for a given person, they will be concatenated and that will provide the name for that person. If the name property is present and none of the name sub properties are present, it will fall back and use that to provide the name.

If a person has neither an "email" property entry nor a "user principal name" property entry, this will result in an error.

Extra white space around value will be trimmed. Cells only containing white space will be assigned to null. We support a maximum CSV size of 190MB.

Required Permissions

You must have organization admin or legal hold organization admin access on the owning organization of the requested directory.

path Parameters
directoryId
required
integer

The legal hold directory id

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetOrganization

Fetch a single organization by id.

Required Permissions

You must be a member of the requested organization.

path Parameters
orgId
required
integer

The organization id

Responses

Response samples

Content type
application/json
{}

GetOrganizationBilling

Fetch monthly billing information for the given organization. By default, fetches data for the current year/month. The result will include database and project billing information for databases owned by the organization. Each month of billing data includes peak and final (end-of-month/current) sizes as well as information about the database/project status in the given month.

Peak sizes reflect the maximum data sizes for the requested month and are used to determine the actual billable size for that month. Final sizes reflect the current size of the collection if requesting the current month, or the size at the end of the requested month otherwise.

Billable status reflects how the database/project is considered for the sake of billing in the requested month. The final status reflects the current (or end-of-month) status, which may be different. For example, if a project was suspended in the middle of a month, it will be billed as active for that month although its final status will be "Suspended".

The status information also includes timestamps for recent status changes (as of the end of the requested month) when applicable, including suspension, deletion request and deletion.

Required Permissions

You must be an org admin for the requested organization.

path Parameters
orgId
required
integer

The organization id

query Parameters
year
integer

The four-digit year (e.g. 2021), defaulting to the current year

month
integer [ 1 .. 12 ]

The month of the year (1 = Jan, ... 12 = Dec), defaulting to the current month

after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

GetOrganizationDatabases

Get all databases owned by a specific organization.

Required Permissions

You must be an org admin for the requested organization.

path Parameters
orgId
required
integer

The organization id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetOrganizationProjects

Get all projects owned by a specific organization

Required Permissions

You must be an org admin for the requested organization.

path Parameters
orgId
required
integer

The organization id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetOrganizationUsers

List all members of a specific organization. To access users on a project, but not within your organization, use GetProjectUsers endpoint

Required Permissions

You must be an org admin for the requested organization.

path Parameters
orgId
required
integer

The organization id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

Database

Database-level operations.

GetDatabaseUsers

List all users with database-level permissions on a the requested database (note that these permissions are separate from project-level access).

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

Database Org Admin

Database-level administrative operations (accessible to org admins).

GetDatabase

Get a specific database by id

Required Permissions

You must have admin permission on the requested database or be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

Responses

Response samples

Content type
application/json
{}

GetDatabaseBilling

Fetch monthly billing information for the given database. By default, fetches data for the current month. Each month of billing data includes peak and final (end-of-month/current) sizes for the database and all of its projects as well as information about the database's status in the given month.

Peak sizes reflect the maximum data sizes for the requested month and are used to determine the actual billable size for that month. Final sizes reflect the current size of the collection if requesting the current month, or the size at the end of the requested month otherwise.

Billable status reflects how the database is considered for the sake of billing in the requested month. The final status reflects the current (or end-of-month) status, which may be different. For example, if a project was suspended in the middle of a month, it will be billed as active for that month although its final status will be "Suspended".

The status information also includes timestamps for recent status changes (as of the end of the requested month) when applicable, including its suspension, deletion request and deletion.

Required Permissions

You must have admin access on the requested database or be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

query Parameters
year
integer

The four-digit year (e.g. 2021), defaulting to the current year

month
integer [ 1 .. 12 ]

The month of the year (1 = Jan, ... 12 = Dec), defaulting to the current month

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetDatabaseProjects

List projects for a specific database identified by id

Required Permissions

You must have admin permission on the requested database or be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetDatabaseSize

Get database size information. This includes document counts and file sizes by document source (natively uploaded documents, processed documents and documents produced on Everlaw). Each document in the database will be counted once, regardless of the number of complete or partial projects in this database.

Required Permissions

You must have admin access on the requested database or be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Native Uploads

Native uploading refers to the ingestion of native-only, unprocessed (and un-numbered/Bates stamped) data into the Everlaw system. During ingestion, the Everlaw processing system will extract child documents (individual emails from an Outlook PST, compressed files from a ZIP, filesystem data from a forensic disc image, etc.), generate PDFs, and extract text and metadata. As documents are extracted and processed they will become available for review on the Everlaw platform.

Datasets and Source Files

Native uploads are organized into objects called Datasets, which provide a means for grouping related source files (e.g. all data in a particular collection or from a specific custodian) as well as defining a shared processing configuration. Each dataset then contains one or more source files uploaded by the user that contain the native data they would like to load into Everlaw. As each source file is uploaded, it will automatically be processed by Everlaw and the extracted documents (and their PDFs, text and metadata) will be available for search and review on the platform.

Processing Configuration

When you create a Dataset, you can also define the processing configuration you would like to use while processing documents uploaded to it. These configuration options are described below, as well as on our platform processing documentation.

Deduplication

This setting configures how to handle exact duplicate documents encountered during native processing. Exact duplicates are determined based on a SHA1 hash of the native file (with custom hashing for certain filetypes, including emails - see our platform documentation for more details). There are three supported options:

  • NONE - no documents in the dataset will be deduplicated
  • ALL - any documents in the dataset that match an existing natively-uploaded document (in any dataset) will be deduplicated
  • WITHIN_CUSTODIAN - any documents in the dataset that match an existing natively-uploaded document (in any dataset) with the same custodian will be deduplicated

When a document is deduplicated, its path and custodian will be added to the All Paths and All Custodians fields on the existing documents.

You can also configure whether or not to "deNIST" the dataset - remove documents whose hashes appear in the NIST NSRL reference hash lists of known software files.

PDF Generation

This setting determines which document types we will attempt to create PDFs for during processing. There are three supported options:

  • DEFAULT - all documents except for types that do not convert well to PDF (primarily spreadsheet-like formats, e.g. Excel, CSV, etc) will be conveted to PDF
  • ALL - all documents (including Excels, CSV, etc) will be converted to PDF
  • NONE - no PDFs will be generated

Image Inlining

This setting determines how and when images are inlined into email bodies (versus extracted as attachments) during processing. This helps prevent the proliferation of attached footer/signature images and icons being extracted as child documents. There are three supported options:

  • SMART - all images that are explicitly inlined (included in the email body) or match Everlaw's heuristics for images that are intended to be inlined, are inlined - all other images are treated as attachments
  • ALL - all images are inlined
  • STRICT - only images that are explicitly inlined (included in the email body) are inlined - all other images are treated as attachments

OCR Language

This setting allows you to specify the particular language to detect when doing optical character recognition (OCR). By default, this is set to 'auto', which can detect and extract all Latin-alphabet languages (e.g. English, French, German) as well as Chinese, Japanese and Korean (CJK languages), with the caveat that autodetection will only detect and extract one language (in addition to English) per page.

You can alternatively provide an ISO/DIS 639-3 language code of a specific supported language you would like to detect (e.g. 'rus' for Russian) - in this mode, OCR will only detect that one language and English.

For more details about configuring an OCR language, see our platform processing documentation.

Page Size

This setting controls the default page size used when generating PDFs. There are two supported options:

  • Letter
  • A4

PowerPoint Speaker Notes

This setting controls whether PowerPoint speaker notes are included when generating PDF and text files. There are three supported options:

  • INCLUDE - include speaker notes with original formatting. PowerPoint notes pages will be displayed in the PDF without modification.
  • INCLUDE_STREAMLINED - include speaker notes with optimized formatting. Slides will be scaled to optimize legibility, with speaker notes text displayed under the slide. Any additional objects in the notes page, such as headers and footers, will be excluded from the PDF.
  • EXCLUDE - speaker notes will be excluded from PDF and text files, and slides will be full-page in the PDF

Timezone

This configuration setting is used to specify the timezone from which the documents were originally collected. This timezone will be assumed for any extracted dates (e.g. metadata) that do not specify an explicit timezone. Email date headers will also be displayed in this timezone when generating PDFs. The value should be a timezone name from the tz (IANA time zone) database, e.g. "America/Los_Angeles", "Europe/London".

Partial Projects

This configuration allows you to specify which partial projects this upload should be included in. Documents uploaded to a database will always be included in all complete projects in that database. By default, they are not included in any partial projects.

Custodians

When creating a dataset, you can specify a default custodian to apply to every file that gets uploaded within it. Later, when uploading a source file to a dataset, you can specify a custodian to apply to that specific file and all its children which will take precedence over the default dataset custodian. You can also specify a mapping from child path (within that source file) to custodian for fine-grained control - for example, if you're uploading a ZIP file with the following directories:

  • Jane Doe - Emails/
  • Jane Doe - Hard Drive/
  • Mike Smith - Emails/

You can specify a child custodians map of

{
    "Jane Doe - Emails/": "Jane Doe",
    "Jane Doe - Hard Drive/": "Jane Doe",
    "Mike Smith - Emails/": "Mike Smith"
}

The end result will be the following:

  • Jane Doe - Emails/ - Custodian "Jane Doe"
  • Jane Doe - Hard Drive/ - Custodian "Jane Doe"
  • Mike Smith - Emails/ - Custodian "Mike Smith"

Passwords

Passwords can be supplied when uploading a new source file. These passwords will be used when attempting to open any encrypted file found in the entire dataset (including child documents and other source files).

Source File Uploading

There are currently two options for uploading new source files to Everlaw - multipart uploading and providing a direct link (URL). The first, multipart uploading, is applicable when you have the file locally (e.g. on a filesystem attached to the computer you're connecting to the Everlaw API). The second, providing a direct link, is applicable when the file you wish to upload is hosted on a publicly accessible server or cloud storage service (e.g. Amazon S3, Google Cloud Storage) to which Everlaw can connect directly.

Multipart Uploading

When sending local files to Everlaw using multipart uploading, each file is transferred in one or more separate parts that are uploaded independently. This allows for parallel, error-resilient and resumable uploading of very large files (up to 5TB). Each part is a contiguous section of the binary content of the file, and can be uploaded in any order. After initiating a source file upload and determining an appropriate part size, you can then upload each part of the file separately - for each part, you request a pre-authenticated URL from Everlaw to which to send the part's content (as a PUT request). After a part is successfully uploaded, the response will include a short string identifier called an ETag; after all parts are finished, you send the collection of ETags to Everlaw to assemble the parts together into the complete file and start processing.

For example, if you're trying to upload a 50GB file, you might select a 50MB part size, so that you have 1,000 parts: part number 1 contains byte range 0-50MB, part number 2 has 50MB-100MB, etc, ... For each part (and in parallel/any order), you request a pre-authenticated URL via the Everlaw API to which you PUT that particular byte range. If any of those individual part uploads fails (e.g. due to network issues), you can request a new URL for that same part and re-try that particular upload without affecting the other parts. Additionally, if the entire upload needs to be resumed, you can list all the parts that have been successfully created (as well as their ETags) via the Everlaw API, determine which have not yet been received, and re-upload only those parts without losing the progress you've already made. Finally, after collecting the 1,000 ETags from each of those uploads, you send those in part order in a final request via the Everlaw API which triggers the assembly of those parts into your original 50GB file and begins processing.

There is a maximum of 10,000 parts per upload and each part must be 5MB to 5GB with the exception of the final part which has no minimum size. For example, if your file is 50.1MB bytes long, possible options include uploading a single 50.1MB part or uploading 5 parts of 10MB plus a final part of 0.1MB. For smaller files (< 5GB) it is reasonable to upload the entire file as a single part, but the 5GB part size limit means that any larger files must be split into multiple parts. A reasonable part size algorithm is:

def determine_part_size(total_file_size):
    # Maximum of (50MB, 1/10000 of the total file size rounding up)
    return max(50000000, 1 + total_file_size / 10000)

For more details about multipart uploads, see the endpoint-specific documentation below.

If the file you are uploading is hosted on a publicly accessible server or cloud storage service, you can provide a direct link (URL) to which Everlaw can connect directly to download the file. These links must not require any additional authentication (API keys, username/password credentials, etc.) other than what is included in the link itself. The server host must also support Range requests via the Range header. Examples of suitable links include pre-signed Amazon S3 URLs and Google Cloud Storage URLs.

Direct links can be provided when creating a new source file. If a link is provided, Everlaw will immediately begin downloading the file and will begin processing when that download finishes; no additional client action is necessary.

Upload Walkthrough

To demonstrate the overall upload process, let's assume we have a 65GB password-protected ZIP we wish to upload. First, we need to determine what dataset we'd like to use - we may already have an existing dataset with our desired processing configuration that we want to add this file to, or we may want to create a new dataset. Let's create a new dataset called "Upload Walkthrough" in our database (id 555) with our desired configuration using the PostDatabaseDataset operation:

POST /v1/databases/555/datasets

{
   "name": "Upload Walkthrough",
   "description": "A demo dataset for walking through the upload process",
   "deduplication": "NONE",
   "timezone": "America/Los_Angeles"
}

Response:

{
  "data": {
      "id": 1201,
      "name": "Upload Walkthrough",
      ...
  }
}

With our target dataset (id 1201), we can create a new source file using the PostDatasetFile operation. We have the file on our local filesystem (not publicly accessible), so we can't provide a directLink; we also want to include password and custodian information. Assuming the ZIP has a few different subdirectories for different custodians, we can set those using the childCustodians parameter:

POST /v1/databases/555/datasets/1201/sourceFiles

{
   "filename": "my_encrypted_collection.zip",
   "passwords": ["my_zip_password"],
   "childCustodians": {
       "Custodian_A_Collection/": "Custodian A",
       "Custodian_B_Collection/": "Custodian B"
   }
}

Response:

{
  "data": {
      "id": 988,
      "state": "UPLOADING",
      ...
  }
}

The source file (id 988) is now in state "UPLOADING" and we can start uploading the individual parts - let's choose a part size of 100MB, giving us 650 parts. We then upload each of those parts - let's walk through part number 25. First, we request a pre-authenticated URL for that part using the PostSourceFilePart operation:

POST /v1/databases/555/sourceFiles/988/parts/25

Response:

{
  "data": {
      "partNumber": 25,
      "url": "https://everlaw-demo.s3.amazonaws.com/..",
      ...
  }
}

Next, we PUT the specific byte range for this part to the generated URL and save the resulting ETag:

PUT https://everlaw-demo.s3.amazonaws.com/...

(bytes 24,000,000,001 - 25,000,000,000, 1-indexed, inclusive)

Response:

HTTP/1.1 200
ETag: "4bb64c06b1a72539e6d3476891daf17b"
...

We then save this ETag header for part 25; once we have all 650 ETags, we can complete the upload (optionally including a SHA1 hash of the entire file contents) using the PostSourceFile operation:

POST /v1/databases/555/sourceFiles/988

{
  "eTags": [..., "4bb64c06b1a72539e6d3476891daf17b", ...]
  "sha1Hash": "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"
}

Response:

{
  "data": {
      "id": 988,
      "state": "PROCESSING",
      ...
  }
}

The source file upload is now complete and the ZIP is processing - the contents will soon be available for review on the platform as Everlaw documents!

Uploading Limits

Everlaw currently imposes a limit of 1000 datasets created via API per database. Datasets created manually (on the platform) do not count towards this limit.

Additionally, there is currently a limit of 1000 source files uploaded via API per dataset (again, source files manually uploaded on the platform do not count towards this limit). We encourage clients with many files to upload to package/compress them (e.g. into ZIP archives) to remain under this limit - for example, you can package any number of files into a single archive and thereby upload them as a single source file.

GetDatabaseDatasets

List all native datasets in the given database.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

PostDatabaseDataset

Create a new native dataset in the given database with the provided configuration.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

Request Body schema: application/json
required
deNISTing
boolean
Default: true
deduplication
string
Default: "ALL"
Enum: "NONE" "ALL" "WITHIN_CUSTODIAN"
description
string
fetchHyperlinkedImages
boolean
Default: true
imageInlining
string
Default: "SMART"
Enum: "ALL" "SMART" "STRICT"
name
required
string
ocrLanguage
string
Default: "auto"

An ISO/DIS 639-3 language code or 'auto' for autodetection

pageSize
string
Default: "Letter"
Enum: "Letter" "A4"

The preferred page size to use when generating PDFs

pdfs
string
Default: "DEFAULT"
Enum: "DEFAULT" "ALL" "NONE"
projects
Array of integers

A list of partial project ids that this upload should be included in

speakerNotes
string
Default: "INCLUDE"
Enum: "INCLUDE" "INCLUDE_STREAMLINED" "EXCLUDE"
timezone
string
Default: "UTC"

A timezone name from the tz (IANA time zone) database

Responses

Request samples

Content type
application/json
{
  • "deNISTing": true,
  • "deduplication": "NONE",
  • "description": "string",
  • "fetchHyperlinkedImages": true,
  • "imageInlining": "ALL",
  • "name": "string",
  • "ocrLanguage": "auto",
  • "pageSize": "Letter",
  • "pdfs": "DEFAULT",
  • "projects": [
    ],
  • "speakerNotes": "INCLUDE",
  • "timezone": "UTC"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetDatabaseDataset

Get a single dataset in a database.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

datasetId
required
integer

The dataset id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetDatasetFiles

List source files uploaded to a given dataset.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

datasetId
required
integer

The dataset id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

prefix
string

An optional prefix used to filter by filename (only files matching the given prefix will be included)

Responses

Response samples

Content type
application/json
{}

PostDatasetFile

Upload a new source file to the selected dataset. You must provide a non-empty filename which must be unique among all source files in the target dataset. If you provide a directLink, it must be a publicly-accessible URL supporting Range requests at which the Everlaw server can fetch the target source file contents. When providing this URL, Everlaw will immediately begin downloading the source file and then begin processing - no additional user action is required. If this link is not provided, the new source file will be in state UPLOADING and you must complete a multipart upload of the file contents.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

datasetId
required
integer

The dataset id

Request Body schema: application/json
required
object

A map from sub-path to custodian for child documents

custodian
string

The default custodian to apply to this file and any children

directLink
string

If provided, a pre-authenticated URL at which Everlaw can download this file

filename
required
string

The filename of the new source file

passwords
Array of strings

An array of passwords to use when attempting to open/decrypt this file (and any other files contained within)

Responses

Request samples

Content type
application/json
{
  • "childCustodians": {
    },
  • "custodian": "string",
  • "directLink": "string",
  • "filename": "string",
  • "passwords": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetSourceFile

Get a single source file in a database.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

sourceId
required
integer

The source file id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

PostSourceFile

Complete the upload of a single source file in a database (after uploading all parts). You must provide the ETags of all individual part uploads in their correct order (by part number).. You can also optionally provide the hex-encoded SHA1 hash of the full source file - if not included, Everlaw will generate this prior to processing which may cause a short delay.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

sourceId
required
integer

The source file id

Request Body schema: application/json
required
eTags
required
Array of strings

The ETags generated during part uploads

sha1Hash
string

The hex-encoded SHA1 hash of the full source file

Responses

Request samples

Content type
application/json
{
  • "eTags": [
    ],
  • "sha1Hash": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetSourceFileParts

List completed parts and ETags for the given source file, useful for resuming interrupted multipart uploads. This listing does not include parts that have not completed uploading or are still in progress.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

sourceId
required
integer

The source file id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

PostSourceFilePart

Initiate an upload for a single part of a source file. Each upload can have a maximum of 10,000 parts, and each part can be 5MB to 5GB in size aside from the last part which has no minimum size. This endpoint returns a URL; you should then PUT the appropriate byte range of the file to that URL. The response from that PUT request will include an ETag header which you must save; after all parts are finished you then send that list of ETags to the PostSourceFile endpoint to complete the upload. These URLs expire approximately one hour after generation.

Note: these URLs connect to Amazon Web Service's (AWS) storage API, which returns XML content, not JSON. Common issues/error codes include:

  • Expired URLs (response code 400) - you must generate a new URL using Everlaw's PostSourceFilePart operation and retry
  • Server errors (response code 5xx, e.g. 500, 502) - you can retry uploading the part with the same URL

For more information on the AWS S3 storage API, see the Multipart Upload overview and the UploadPart documentation.

Required Permissions

You must have admin access on the requested database, or, if the database allows org admin access, be an org admin for its owning organization.

path Parameters
databaseId
required
integer

The database id

sourceId
required
integer

The source file id

partNum
required
integer [ 1 .. 10000 ]

The part number

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Project

Project-level operations.

GetProjectAssignmentGroups

List all assignment groups and assignments on the given project.

This is a list of assignment groups where each contains a property assignments that lists the assignments under that group.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

GetProjectBatesPrefixes

List all Bates number prefixes on the given project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

GetProjectBinders

List all binders on the given project, including their names, IDs, and owning users.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjectCodes

List all categories and codes on the given project.

This is a list of categories where each contains a property codes that lists the codes under that category.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

GetProjectDatasets

List all native datasets in the given project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

GetProjectFreeformCodes

List all searchable freeform codes on the given project. The list includes the name, id, and format of each freeform code.

The different formats are:

  • "TEXT" - simple text-valued codes, searchable as exact values or non-exact parsed values.
  • "DATE_TIME" - date and time codes.
  • "NUMBER" - number codes.

More information about freeform codes can be found in Freeform codes.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

GetProjectGroups

List user groups for a given project

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjectGroup

Get a specific user group for a given project

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

groupId
required
integer

Responses

Response samples

Content type
application/json
{}

GetGroupUsers

List users in a given user group in a project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

groupId
required
integer
query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

GetProjectMetadataFields

List all searchable metadata fields on the given project. The list is sorted by field name, and includes the name, the internal ID, and the format.

The different field formats are:

  • "TEXT" - simple text-valued fields, searchable as exact values or non-exact parsed values.
  • "ADDRESS_LIST" - multi-valued email recipients metadata fields, each value parsed into Contact Name, email address and domain.
  • "ADDRESS_FROM" - single-valued email senders (From) fields.
  • "DATE_TIME" - date and time fields.
  • "BATES" - Bates numbers fields.
  • "SHA1" - SHA1 hash value fields.
  • "MD5" - MD5 hash value fields.
  • "NUMBER" - number fields.

More information about metadata formats can be found in Searching Metadata.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

GetProjectProcessedUploads

List all processed uploads on the given project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjectProductions

List all productions on the given project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjectSearchTermReports

List all search term reports on the given project.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{}

GetProjectUsers

Get users with explicit permissions on a given project (this does not include org admins or other users with implicit access).

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
after
integer

The id of the element after which to start this page

limit
integer [ 1 .. 200 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
}

GetProjectUser

Get info on a specific user on a particular project

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

userId
required
integer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Project Org Admin

Project-level administrative operations (accessible to org admins).

GetProject

Get a specific project by id.

Required Permissions

You must have read access on the requested project or be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{}

GetProjectBilling

Fetch monthly billing information for the given project. By default, fetches data for the current month. Each month of billing data includes peak and final (end-of-month/current) sizes as well as information about the project's status in the given month.

Peak sizes reflect the maximum data sizes for the requested month and are used to determine the actual billable size for that month. Final sizes reflect the current size of the collection if requesting the current month, or the size at the end of the requested month otherwise.

Billable status reflects how the project is considered for the sake of billing in the requested month. The final status reflects the current (or end-of-month) status, which may be different. For example, if a project was suspended in the middle of a month, it will be billed as active for that month although its final status will be "Suspended".

The status information also includes timestamps for recent status changes (as of the end of the requested month) when applicable, including its suspension, deletion request and deletion.

Required Permissions

You must have admin access on the requested project or be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

query Parameters
year
integer

The four-digit year (e.g. 2021), defaulting to the current year

month
integer [ 1 .. 12 ]

The month of the year (1 = Jan, ... 12 = Dec), defaulting to the current month

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

GetProjectSize

Get project size information for a specific project. This includes current document counts and file size information by document source (natively uploaded documents, processed documents and documents produced on Everlaw).

Required Permissions

You must have analytics access on the requested project or be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Search

Running a search query on the project involves calling the PostProjectSearch endpoint, providing the term property (see the different terms below), and a query property, specific for the type of term.

Assigned term

This term searches for documents matching the given assignment criteria. See GetProjectAssignmentGroups for obtaining the project assignment groups, assignments and assignees.

Query properties:

  • userId (integer, optional) - Searches for all documents assigned to the specific user. The userId must match an assigneeId of any assignment.
  • assignmentGroup (object, optional)
    • id (int) - the id of the assignment group. See GetProjectAssignmentGroups for project assignment groups endpoint.
    • criteria (string, Default: "ALL_IN_GROUP", Enum: "ALL_IN_GROUP" "ASSIGNED" "UNASSIGNED" "ASSIGNMENT" "USER") - additional criteria for selection.
    • userId (integer, only if criteria is "USER") - the user id of the assignee.
    • assignmentId (integer, only if criteria is "ASSIGNMENT") - the specific assignment id.
    • reviewStatus (string, Default: "ANY", Enum: "ANY" "REVIEWED" "NOT_REVIEWED") - whether to select documents that have been reviewed, not reviewed (according to the review criteria of the group), or either.

Exactly one of userId or assignmentGroup should be provided.

Example query

{
  "term": "ASSIGNED", 
  "query": {
    "assignmentGroup": {
      "id": 11,
      "criteria": "ASSIGNMENT",
      "assignmentId": 22,
      "reviewStatus": "NOT_REVIEWED"
    }
  }
}

Bates/Control term

This term searches for documents with Bates numbers matching the given properties.

Query properties:

  • prefix (string, optional) - the prefix of the Bates number of the document. See GetProjectBatesPrefixes for the available Bates number prefixes for the project. Omitted or null means "any prefix".
  • pageSearch (boolean, optional) - whether to search for Bates numbers of pages in addition to documents
  • numRange (object, optional) - when omitted, searches for all Bates with the given (mandatory) prefix
    • begin (string, optional) - the lower bound of the Bates number (inclusive)
    • end (string, optional) - the upper bound of the Bates number (inclusive)
      Valid numRange must include at least one of begin or end. If only one is provided, it's an open-ended range search. To search for a specific value, set both begin and end to the desired value.

Bates numbers are required here as strings to accommodate Australian Doc IDs, but will be treated as numbers for all intents and purposes. For example, leading zeroes are not required (a search for ABC1 will return ABC001).

Example query

{
  "term": "BATES",
  "query": {
    "prefix": "ABC",
    "pageSearch": true,
    "numRange": {
      "begin": "1000",
      "end": "1999"
    }
  }
}

Billable Size term

This term searches for documents with billable size in the given range.

Query properties:

  • begin (integer, optional) - lower bound, in bytes (inclusive)
  • end (integer, optional) - upper bound, in bytes (inclusive)

Valid queries must include at least one of begin or end. If only one is provided, it's an open-ended range search. To search for an exact number, set both begin and end to the desired number.

Example query

{
  "term": "BILLABLE_SIZE",
  "query": {
    "begin": 1000000
  }
}

Binder term

This term searches for binders matching the given criteria

  • binderId (integer, optional): The id of the binder to search for. See [GetProjectBinders](#operation/GetProjectBinders) for the available binders for the project. If 'binderId' is omitted or null`, the search returns all binders on the project.
  • userId (integer, optional) - See GetProjectUsers for project users endpoint.
  • groupId (integer, optional) - See GetProjectGroups for project groups endpoint.
    Only one of userId or groupId may be provided, but not both. When neither is provided, the search is for binders regardless of the user or user group that applied it.
  • dateRange (object, optional)
    • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
    • end (string, optional) - the upper bound of the date range, in ISO 8601 format.
      Valid dateRange must include at least one of begin or end. If only one is provided, it's an open-ended range search.

If dateRange is null or omitted the search is for currently applied binders. Note that in that case the search must not specify a specific userId or groupId.

Example query

{
  "term": "BINDER", 
  "query": {
    "binderId": 7, 
    "userId": 12345,
    "dateRange": {
      "begin": "2022-01-01T00:00:00.00Z",
      "end": "2022-02-01T00:00:00.00Z"
    }
  }
}

Contents term

This term searches document text. It allows for all of the complex text searching supported by the Contents search term in the UI including, for example, proximity and fuzzy searches. See Advanced Content Searches.

Query properties:

  • value (string, optional): the text to search for
  • hasAnyText (boolean, optional): if true, docs that have any text at all, if false, finds docs that have no text Exactly one of value or hasAnyText should be provided.

Example search for a value:

{
  "term": "CONTENTS", 
  "query": {
    "value": "Cow"
  }
}

Example search for documents that have any text:

{
  "term": "CONTENTS", 
  "query": {
    "hasAnyText": true
  }
}

Coded term

This term searches for documents coded matching the given criteria.

Query properties:

  • labelId (integer, optional): The id of the label (category or code) to search for. See GetProjectCodes for the available categories and codes for the project. If labelId is omitted or null, the search returns documents with any code on the project.
  • userId (integer, optional) - See GetProjectUsers for project users endpoint.
  • groupId (integer, optional) - See GetProjectGroups for project groups endpoint.
    Only one of userId or groupId may be provided, but not both. When neither is provided, the search is for coding regardless of the user or user group that coded it.
  • dateRange (object, optional)
    • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
    • end (string, optional) - the upper bound of the date range, in ISO 8601 format.
      Valid dateRange must include at least one of begin or end. If only one is provided, it's an open-ended range search.

If dateRange is null or omitted the search is for currently coded documents. Note that in that case the search must not specify a specific userId or groupId.

Example query

{
  "term": "CODED", 
  "query": {
    "labelId": 7, 
    "userId": 12345,
    "dateRange": {
      "begin": "2022-01-01T00:00:00.00Z",
      "end": "2022-02-01T00:00:00.00Z"
    }
  }
}

Deduplicate term

This term allows to deduplicate among search hits for the given search operand. For details, see Deduplicate among search hits.

Query properties:

  • operand (object): The search to be deduplicated. Can be of any supported term.

Example:

{
  "term": "DEDUPLICATE", 
  "query": {
    "operand": { 
      "term": "METADATA",
      "query": {
        "field": "Custodian", 
        "value": "Jane"
      }
    }
  }
}

Freeform Codes term

This term searches for documents matching the given freeform code criteria.

Query properties:

  • id (int): The freeform code id.
  • exact (boolean, Default: false): TEXT format allow searching for exact value. If this property is true, exact value search is performed. Otherwise, free-form substring search (including proximity search, regex, etc) is performed.
  • value: The information you're searching for. The expected inputs for value depend on the format of the code you specified. See Metadata term for information about the TEXT, DATE_TIME and NUMBER formats.
    • (No value) and (Any value): Freeform codes support searching for documents without any value in that code, denoted by (No value) on search terms on the Everlaw search page. To search for no value, set the value property to null or omit it. To search for documents with any value in a specified code, denoted by (Any value) on the Everlaw search page, instead use the NOT logical term to negate a search for a null value.

See GetProjectFreeformCodes for the available codes and their formats, on a specific project.

Example query

{
  "term": "FREEFORM_CODES", 
  "query": {
    "id": 26, 
    "value": "Everlaw Oakland"
  }
}

Grouping term

This term allows to group search hits for the given search operand, and optionally filter out certain context from groups.

With this term, the PostProjectSearch result numGroups metric indicates the number of groups based on the grouping criteria. Without this term, numGroups is always equal to numDocs.

Query properties:

  • grouping (string, Enum: "ATTACHMENTS" "EMAIL_THREADS" "EXACT_DUPLICATES" "VERSIONS"):
    Grouping allows you to organize your search hits by context: exact duplicates, attachments, email threads, or document versions. For details, see Grouping.
  • removeFromGroup (string, Enum: "NONE" "PARENT" "CHILDREN" "SEARCH_HITS" "NON_HITS" "NON_INCLUSIVE_EMAILS", Default: "NONE"):
    Once you group your search hits, you have the option to remove certain contexts from that grouping: parents, children, search hits, grouped non-hits, and non-inclusive emails. For details, see Removal.
  • operand (object): The search to be grouped. Can be of any supported term.

Example:

{
  "term": "GROUPING", 
  "query": {
    "grouping": "ATTACHMENTS",
    "removeFromGroup": "PARENT",
    "operand": { 
      "term": "METADATA",
      "query": {
        "field": "Custodian", 
        "value": "Jane"
      }
    }
  }
}

Has Format term

This term searches for documents for which the given format is available.

Query properties:

  • format (string, Enum: "IMAGE" "NATIVE" "PDF" "TEXT")

Example query

{
  "term": "HAS_FORMAT", 
  "query": {
    "format": "NATIVE"
  }
}

Logical term

This term searches for documents matching a logical compound query, combining other terms via OR, AND, or NOT logical operators.

Query properties:

  • operator (string, Enum: "AND" "OR" "NOT"): the logical operator.
  • operands (array, only if operator is "AND" or "OR"): search terms that must all, or any, match for this query to match, depending on whether the operator is "AND" or "OR", respectively. Can be any number of any supported terms.
  • operand (object, only if operator is "NOT"): search term that is to be negated. Can be any supported term.

Example "AND":

{
  "term": "LOGICAL", 
  "query": {
    "operator": "AND",
    "operands": [ 
      {
        "term": "METADATA",
        "query": {
          "field": "Custodian", 
          "value": "Jane"
        }
      },
      {
        "term": "METADATA",
        "query": {
          "field": "Subject", 
          "value": "Hello"
        }
      }
    ]
  }
}

Example "NOT":

{
  "term": "LOGICAL", 
  "query": {
    "operator": "NOT",
    "operand": { 
      "term": "METADATA",
      "query": {
        "field": "Custodian", 
        "value": "Jane"
      }
    }
  }
}

Metadata term

This term searches for documents matching the given metadata field criteria.

Query properties:

  • field (string): The name of a searchable metadata field of the project
  • exact (boolean, Default: false): TEXT, MD5 and SHA1 formats allow searching for exact value. If this property is true, exact value search is performed. Otherwise, free-form substring search (including proximity search, regex, etc) is performed.
  • value: The information you're searching for. The expected inputs for value depend on the format of the field you specified. Each field format is described in more detail below.
    • (No value) and (Any value): All metadata fields, regardless of format, support searching for documents without any metadata in that field, denoted by (No value) on search terms on the Everlaw search page. To search for no value, set the value property to null or omit it. To search for documents with any value in a specified field, denoted by (Any value) on the Everlaw search page, instead use the NOT logical term to negate a search for a null value.

See GetProjectMetadataFields for the available fields and their formats, on a specific project. In addition to the fields returned by that endpoint, the following smart aliases are available by name:

  • "All Text Fields" (TEXT format)
  • "Parties" (ADDRESS_LIST format)
  • "Recipients" (ADDRESS_LIST format)
  • "Primary Date" (DATE_TIME format)
  • "Family Date" (DATE_TIME format)
  • "All Date Fields" (DATE_TIME format)

TEXT, MD5, SHA1 formats

The value property is a string.

Example query

{
  "term": "METADATA", 
  "query": {
    "field": "Custodian", 
    "value": "Jane"
  }
}

Exact query

{
  "term": "METADATA", 
  "query": {
    "field": "Custodian",
    "exact": true,
    "value": "Jane Doe"
  }
}

ADDRESS_LIST format

Fields that are address lists, such as To, CC and Parties contains multiple addresses. Each address can contain a name and/or an email address, intended to represent a single party or individual. If an email address exists in a field, the domain name is extracted from it as well.

The "value" property is an object, with the following properties:

  • operator (string, Default: "ANY", Enum: "ANY" "ALL") - whether either of the terms provided should appear in the field, or all of them must, to generate a hit.
  • exclusive (boolean, Default false) - whether nothing else other than the provided terms should appear in the field, i.e. the field should exclusively include communication between the given parties without anyone else included.
  • terms array of objects. Each term object includes the following properties:
    • value (string) - the value to search for.
    • kind (string, Enum: "NAME" "EMAIL" "DOMAIN" "TEXT")
      The term kinds are defined as follows:
      "NAME" searches for value as a Contact Name, including its associated email addresses.
      "EMAIL" searches for value as an email address.
      "DOMAIN" searches for value as a domain of the field's email addresses.
      "TEXT" free-form text search for value within the field.

Example query

{
  "term": "METADATA",
  "query": {
    "field": "To",
    "value": {
      "operator": "ALL",
      "exclusive": true,
      "terms":[
        {
          "value": "John Doe",
          "kind": "NAME"
        },
        {
          "value": "Jane Doe",
          "kind": "NAME"
        }
      ]
    }
  }
}

ADDRESS_FROM format

This is the format of the From metadata field, representing a sender of a message. Similar to ADDRESS_LIST but each document can contain only up to one address.

The "value" property is an object, with the following property:

  • terms array of objects. When more than one term is given, the search is for any of them to match. Each term object includes the following properties:
    • value (string) - the value to search for.
    • kind (string, Enum: "NAME" "EMAIL" "DOMAIN" "TEXT")
      See ADDRESS_LIST above for their meaning.

Example query

{
  "term": "METADATA",
  "query": {
    "field": "From",
    "value": {
      "terms":[
        {
          "value": "@everlaw.com",
          "kind": "DOMAIN"
        },
        {
          "value": "Everlaw",
          "kind": "TEXT"
        }
      ]
    }
  }
}

DATE_TIME format

The "value" property is an object, with the following properties:

  • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
  • end (string, optional) - the upper bound of the date range, in ISO 8601 format.

Valid queries must include at least one of begin or end. If only one is provided, it's an open-ended range search.

Example query

{
  "term": "METADATA",
  "query": {
    "field": "Date Sent",
    "value": {
      "begin": "2007-12-03T10:15:00.00Z",
      "end": "2007-12-03T11:15:00.00Z"
    }
  }
}

BATES format

The "value" property is an object, with the following properties:

  • prefix (string, optional) - the prefix of the Bates represented by the field. Missing or null means "any prefix"
  • numRange (object, mandatory)
    • begin (string, optional) - the lower bound of the Bates number (inclusive)
    • end (string, optional) - the upper bound of the Bates number (inclusive)
      Valid numRange must include at least one of begin or end. If only one is provided, it's an open-ended range search. To search for a specific value, set both begin and end to the desired value.

Bates numbers are required here as strings to accommodate Australian Doc IDs, but will be treated as numbers for all intents and purposes. For example, leading zeroes are not required (a search for ABC1 will return ABC001).

Example query

{
  "term": "METADATA",
  "query": {
    "field": "Other Bates",
    "value": {
      "prefix": "ABC",
      "numRange": {
        "begin": "1000",
        "end": "1999"
      }
    }
  }
}

NUMBER format

The "value" property is an object, with the following properties:

  • begin (integer, optional) - the lower bound of the number (inclusive)
  • end (integer, optional) - the upper bound of the number (inclusive)

Valid queries must include at least one of begin or end. If only one is provided, it's an open-ended range search. To search for an exact number, set both begin and end to the desired number.

Example query

{
  "term": "METADATA",
  "query": {
    "field": "Exhibit Number",
    "value": {
      "begin": 2,
      "end": 4
    }
  }
}

Native Uploaded term

This term searches for documents that were uploaded via a native data upload.

Query properties:

  • datasetId (integer, optional): The id of the dataset to search for. See GetDatabaseDatasets for the available datasets for the database (not all might be available for the project). If omitted or null, the search is for any dataset (any native upload).

Example query

{
  "term": "NATIVE_UPLOADED", 
  "query": {
    "datasetId": 7
  }
}

Num Pages term

This term searches for documents with number of pages in the given range.

Query properties:

  • begin (integer, optional) - lower bound (inclusive)
  • end (integer, optional) - upper bound (inclusive)

Valid queries must include at least one of begin or end. If only one is provided, it's an open-ended range search. To search for an exact number, set both begin and end to the desired number.

Example query

{
  "term": "NUM_PAGES",
  "query": {
    "begin": 100
  }
}

Processed Uploaded term

This term searches for documents that were uploaded via a processed data upload.

Query properties:

  • uploadId (integer, optional): The id of the upload to search for. If omitted or null, the search is for any upload (any processed upload).

Example query

{
  "term": "PROCESSED_UPLOADED", 
  "query": {
    "uploadId": 78 
  }
}

Processing Flag term

This term searches for documents with the given processing flag.

Query properties:

  • flag (string, Enum: "CONTAINER_DOC" "EMBEDDED_FILE" "EMBEDDED_FILE_ERROR" "EMPTY_TEXT" "ENCRYPTED" "FLAGGED_MALICIOUS" "HAS_OCR" "HAS_PLACEHOLDER_PDF" "HAS_TRANSCODED_OUTPUT" "HAS_TRANSCRIPTION" "HAS_VALID_TRANSCRIPTION" "METADATA_ERROR" "NIST_DUPLICATE" "OCR_ERROR" "OPENED_WITH_PASSWORD" "PARTIAL_SUPPORT" "UNKNOWN_DOC_TYPE")

Example query

{
  "term": "PROCESSING_FLAG", 
  "query": {
    "flag": "ENCRYPTED"
  }
}

Processing State term

This term searches for documents with the given processing state (stage and status.)

Query properties:

  • stage (string, Enum: "EXAMINE" "PDF" "TEXT")
  • status (string, Enum: "SUCCESS" "ERROR")

Example query

{
  "term": "PROCESSING_STATE", 
  "query": {
    "stage": "PDF",
    "status": "SUCCESS"
  }
}

Produced term

This term searches for documents matching the given production criteria. See GetProjectProductions for obtaining the project productions.

Query properties:

  • productionId (integer, optional) - if provided, searches for documents produced by this production (or the originals, depending on the whichDocs parameter). Otherwise searches for any produced (or original) documents.
  • whichDocs (string, Default: "PRODUCED", Enum: "PRODUCED" "ORIGINAL") - whether to search for the produced documents, or the originals they were produced from.
  • flag (String, optional, Enum: "ENDORSED_BY_CODE" "ERROR_DOCUMENT" "HAS_OCR_TEXT" "NO_SOURCE_IMAGES" "OCR_ERROR" "PLACEHOLDER_IMAGE" "REDACTED_DOCUMENT" "WITHHELD_DOCUMENT") - if provided, searches for documents with the given production flag.

Example query

{
  "term": "PRODUCED", 
  "query": {
    "productionId": 11,
    "whichDocs": "PRODUCED",
    "flag": "REDACTED_DOCUMENT"
  }
}

Project term

This term searches for documents of other partial projects within the database.

Query properties:

  • id (integer) - The project id. Must be within the same database as the project this search is run on, and must be a partial project. See GetDatabaseProjects for obtaining the projects of the database.

Example query

{
  "term": "PROJECT", 
  "query": {
    "id": 72
  }
}

Promotion Code term

This term searches for documents with promotion codes matching the given criteria. This term is only available on ECA projects. For details, see Early Case Assessment Databases.

Query properties:

  • code (string, optional, Enum: "CUSTODIAN" "DATE_RANGE" "KEYWORD" "OTHER" "PRODUCED" "UNITIZED" "UPLOADED_DIRECTLY") -
    If code is omitted or null, the search returns documents with any promotion code on the project.
  • userId (integer, optional) - See GetProjectUsers for project users endpoint.
  • groupId (integer, optional) - See GetProjectGroups for project groups endpoint.
    Only one of userId or groupId may be provided, but not both. When neither is provided, the search is for promotion codes regardless of the user or user group that coded it.
  • dateRange (object, optional)
    • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
    • end (string, optional) - the upper bound of the date range, in ISO 8601 format.
      Valid dateRange must include at least one of begin or end. If only one is provided, it's an open-ended range search.

If dateRange is null or omitted the search is for currently coded documents. Note that in that case the search must not specify a specific userId or groupId.

Example query

{
  "term": "PROMOTION_CODE", 
  "query": {
    "code": "KEYWORD", 
    "userId": 12345,
    "dateRange": {
      "begin": "2022-01-01T00:00:00.00Z",
      "end": "2022-02-01T00:00:00.00Z"
    }
  }
}

Redactions term

This term searches for documents matching the given redaction criteria.

Query properties:

  • stamped (object, optional) - If this parameter is provided the search is only for stamped redactions. Otherwise, it includes redactions that are not stamped.
    • stamp (string, optional) - The specific stamp to search for. If omitted or null, the search is for any stamped redaction.
  • type (string, Default: "ALL", Enum: "ALL" "NON_METADATA_ONLY" "METADATA_ONLY") - Filter by redaction type.
  • userId (integer, optional) - See GetProjectUsers for project users endpoint.
  • groupId (integer, optional) - See GetProjectGroups for project groups endpoint.
    Only one of userId or groupId may be provided, but not both. When neither is provided, the search is for redactions by any user.
  • dateRange (object, optional)
    • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
    • end (string, optional) - the upper bound of the date range, in ISO 8601 format.
      Valid dateRange must include at least one of begin or end. If only one is provided, it's an open-ended range search.

If dateRange is provided, the search is for redactions that were created or updated in the given range.

Example query

{
  "term": "REDACTIONS", 
  "query": {
    "stamped": {
      "stamp": "TOP SECRET"
    },
    "type": "NON_METADATA_ONLY",
    "userId": 77,
    "dateRange": {"end": "2022-01-04T00:00:00Z"}
}

Search Term Report term

This term searches for documents matching Search Term Reports criteria. See GetProjectSearchTermReports for obtaining the project search term reports.

Query properties:

  • id (integer, optional) - The search term report id. If omitted or null, the search is for hits of any search term report on the project.
  • whichDocs (string, Default: "HITS_AND_FAMILY_MEMBERS_OF_HITS", Enum: "HITS_AND_FAMILY_MEMBERS_OF_HITS" "ONLY_HITS" "ONLY_FAMILY_MEMBERS_OF_HITS") - criteria for inclusion in this search.

Example query

{
  "term": "SEARCH_TERM_REPORT", 
  "query": {
    "id": 72,
    "whichDocs": "ONLY_FAMILY_MEMBERS_OF_HITS"
  }
}

Type term

This term searches for documents of the given type.

Query properties:

  • type (string, Enum: "AUDIO" "BINARY" "CAD" "CALENDAR", "CHAT", "COMPRESSED", "DATABASE", "DOCUMENT", "EMAIL", "EMPTY_FILE", "GIS", "HTML", "IMAGE", "MAILBOX", "MEETING", "OTHER", "PDF", "PRESENTATION", "PROFILE", "PROJECT_MANAGEMENT", "SPREADSHEET", "TEXT", "TRANSCRIPT", "UNKNOWN", "VIDEO")

Example query

{
  "term": "TYPE", 
  "query": {
    "type": "SPREADSHEET"
  }
}

Viewed term

This term searches for documents with views matching the given criteria.

Query properties:

  • userId (integer, optional) - See GetProjectUsers for project users endpoint.
  • groupId (integer, optional) - See GetProjectGroups for project groups endpoint.
    Only one of userId or groupId may be provided, but not both. When neither is provided, the search is for views by any user.
  • dateRange (object, optional)
    • begin (string, optional) - the lower bound of the date range, in ISO 8601 format. e.g. 2007-12-03T10:15:30.00Z
    • end (string, optional) - the upper bound of the date range, in ISO 8601 format.
      Valid dateRange must include at least one of begin or end. If only one is provided, it's an open-ended range search.

If dateRange is null or omitted the search is for any time.

Example query

{
  "term": "VIEWED", 
  "query": {
    "userId": 12345,
    "dateRange": {
      "begin": "2022-01-01T00:00:00.00Z",
      "end": "2022-02-01T00:00:00.00Z"
    }
  }
}

PostProjectSearch

Run a search query on the project and return the number of documents it matches, the number of document groups within the matching documents (see Grouping term), along with optionally requested additional summary metrics.

Required Permissions

You must have read access on the requested project, or, if the project's database allows org admin access, be an org admin for its owning organization.

path Parameters
projectId
required
integer

The project id

Request Body schema: application/json
required
extraSummaryMetrics
Array of strings
Default: []
Items Enum: "NUM_PAGES" "BILLABLE_SIZE"

Optional extra summary metrics requested in addition to number of documents

query
required
object <JSON>

JSON object of the term-specific search query specification

term
required
string

The search term. Enum: "ASSIGNED" "BATES" "BILLABLE_SIZE" "BINDER" "CODED" "CONTENTS" "DEDUPLICATE" "FREEFORM_CODES" "GROUPING" "HAS_FORMAT" "LOGICAL" "METADATA" "NATIVE_UPLOADED" "NUM_PAGES" "PROCESSED_UPLOADED" "PROCESSING_FLAG" "PROCESSING_STATE" "PRODUCED" "PROJECT" "PROMOTION_CODE" "REDACTIONS" "SEARCH_TERM_REPORT" "TYPE" "VIEWED"

Responses

Request samples

Content type
application/json
{
  • "extraSummaryMetrics": [
    ],
  • "query": {
    },
  • "term": "LOGICAL"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}