][ Public API (v1.3.0)

Download OpenAPI specification:Download

Introduction

Welcome to the IPRO Public API.

You can use SwaggerUI to test requests.

There is a sample usage script in JavaScript. To run it you'll need node.js 14+ with axios package installed.

An example demonstrating advanced export workflows is also available.

Example scripts for chunked file upload are provided for PowerShell and bash.

Authentication

Creating a Public API Client

To authenticate, a Public API client must be created in the IPRO Enterprise website, under System Manager. Only users in the "SuperAdmin" group can create Public API Clients.

The client_id and client_secret set, during the API client creation, can be used to obtain a token. (example script here)

bearerToken

APIs are secured using bearer JSON Web Tokens (JWTs), issued by IPRO Identity Server. The token is expected to be in the Authorization header of a request. The value is expected to have the bearer JWT.

Example header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Tokens can be retrieved from the IPRO Identity Server using OAuth2.0 flow with client credentials grant type. The token endpoint can be found in the configuration discovery document. Example URL: https://<your_url>/auth/.well-known/openid-configuration.

API endpoints are documented with the scopes required to access. The scopes must be requested when sending the below client credentials request to IPRO Identity Server.

The below request example can be used to obtain a token. Replace Host, client_id, and client_secret with actual values.

POST /auth/connect/token HTTP/1.1
Host: example-site.ipro.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=xxxxxxxx
&client_secret=xxxxxxxx
&scope=ipro.papi%20ipro.api%20ipro.superadmin

Quick Reference

Versioning

You can check what is the current version via OpenAPI description document's info.version value.

Typical version looks like v1.3, where:

  • v1 is a major version. It corresponds to server URL prefix where API is accessible: https://<host>/v1/cases. It is incremented when the contract introduces any breaking changes.
  • .3 is a minor version. It is incremented for non-breaking changes.

Special type is a preview version. For example, v1.0-preview.1 is a preview version for v1.0. Any changes between preview versions v1.0-preview.2 and v1.0-preview.1 might be backward incompatible.

Response Envelope

All responses follow the format:

{
    "data": {},
    "error": {
        "code": "API0012",
        "message": "An error occurred. See logs for further details.",
        "exceptionMessage": "One or more errors occurred. (Failed to subscribe. ResponseErrorMsg=[Object cannot be cast from DBNull to other types.])"
    },
    "pagination": {}
}
  • data is not present or null if there is an error
  • error is not present or null if there is no error
  • pagination is present only for paginated collections

Pagination

Requests that return multiple results will be paginated to 100 items by default. You can use the pageNumber parameter to specify which page of data to retrieve. Pages start from 1.

To set page size, you use the pageSize query param. This sets the maximum page size. Please note that this does not guarantee that, that many items will be returned, even if there are more items than the maximum page size. It does guarantee that no more than the number provided will be returned.

API responses return pre-built pagination links first, prev, next and last and client applications are encouraged to follow these links for pagination.

Filtering

All filtering for collections uses filter query parameter. Beware, not all collections support all filtering capabilities described in this section.

Example: &filter=name@=awesome title,jobType==imaging (items with a name that contains the phrase "awesome title" and jobType equals "imaging")

filter is a comma-delimited list of {Name}{Operator}{Value} where

  • {Name} is the name of a property. You can also have multiple names (for OR logic) by using a pipe delimiter and parentheses, eg. (LikeCount|CommentCount) > 10 asks if LikeCount or CommentCount is >10
  • {Operator} is one of the supported operators.
  • {Value} is the value to use for filtering. You can also have multiple values (for OR logic) by using a pipe delimiter, eg. Title@=new|hot will return items with titles that contain the text "new" or "hot".

Notes:

  • You can use backslashes to escape commas and pipes within value fields.
  • You can have spaces anywhere except within {Name} or {Operator} fields.
  • Nested objects can be referenced with periods . between property names, such as: queue.pending>=10.

Operators:

Operator Meaning
!= not equals
!@= does not contain
!@=* case-insensitive string does not contain
!_= does not Starts with
!_=* case-insensitive string does not starts with
< less than
<= less than or equal to
== equals
==* case-insensitive string equals
> greater than
>= greater than or equal to
@= contains
@=* case-insensitive string contains
_= starts with
_=* case-insensitive string starts with

Updating Resources

If not stated otherwise, the main method for update is using PATCH with JSON Merge Patch format. Refer to the brief explanation here.

You may notice that some fields are still required in update requests, for example schedule.type. Generally, this can be expected for fields in nested and/or polymorphic objects because we want to make sure that change is intentional and doesn't cause unexpected side-effects.

Asynchronous Operations

Some operations are marked as asynchronous, because they might require some time to complete. Such operations return operationLocation link in the response, which can be used to track operation status (see Operations for details).

Checking operation status via operation endpoint follows polling pattern. But we also support webhooks. The workflow is (for example, case creation):

  1. Register webhook and subscribe to case creation events. (see User notifications for details)
  2. Send request to create a case.
  3. After case creation completion you'll be notified via webhook that case was created via event Enterprise.Case.Created (or if not, with the event Enterprise.Case.CreateFailed).

Most of the events can be traced back to the requests that triggered them via correlation id.

Changelog

All v1.0.0 thru v1.2.0 interactions remain valid; only additions have been made.

v1.3.0 (IPRO release 2022.11.0)

  • Added OCR. New endpoints:
    • /workflows/ocr
    • /workflows/ocr/{id}
    • /workflows/ocr/{id}/pause
    • /workflows/ocr/{id}/resume
    • /workflows/ocr/{id}/cancel

v1.2.0

  • Added reporting. New endpoints:
    • /reports/result/{id}
    • /workflows/{workflowType}/{id}/reports
    • /workflows/{workflowType}/{id}/reports/{reportId}
  • Updated tags: Workflow Reports -> Workflow Status
  • New event notification type: Enterprise.Report.Executed

v1.1.0 (IPRO release 2022.10.0)

  • Added export management and workflows. New endpoints:
    • /exportSeries/{id}
    • /workflows/export/{id}
    • /workflows/export/{id}/pause
    • /workflows/export/{id}/resume
    • /workflows/export/{id}/cancel
    • /workflows/export/{id}/documents
    • /workflows/export
    • /cases/{id}/exportSeries
    • /cases/{id}/workflows/export

Modified Endpoints

POST /cases

  • Request body updated
    • New property: capabilities.ingestion.baseCase.includeAllExportSeries
    • New property: capabilities.ingestion.exportErrorDocuments
    • New property: capabilities.ingestion.exportIntervalMinutes

GET /cases/{id}

  • Modified response: 200
    • New property: data.capabilities.ingestion.activeExportSeriesId
    • New property: data.capabilities.ingestion.exportErrorDocuments
    • New property: data.capabilities.ingestion.exportIntervalMinutes

PATCH /cases/{id}

  • Request body updated
    • New property: capabilities.eda.enabled
    • New property: capabilities.ingestion
    • New property: capabilities.review

GET /cases/{id}/workflows/ingestion and GET /workflows/ingestion

  • Modified response: 200
    • New property: data.items[*].activeExportSeriesId
    • New property: data.items[*].documentCount

GET /workflows/ingestion/{id}

  • Modified response: 200
    • New property: data.activeExportSeriesId
    • New property: data.documentCount

v1.0.0

  • Initial public release.

Connectors

Use connectors to structure data ownership. There are several categories of connectors:

  • live connectors (e.g., Box, M365, etc)
  • archive connectors (used for storing data in NetGovern-specific format)

Retrieve a list of connectors for a client

Retrieve a list of all connectors for a client.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)
path Parameters
id
required
string [ 1 .. 500 ] characters

The resource identifier string

Responses

Response samples

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

Uploads

Allows uploading your own data for ingestion workflows.

To preserve data integrity, particularly document dates, only archive/container type files can be uploaded. An error will occur if you attempt to import a file that is not in an archive/container format. Allowed formats:

  • File archives (such as .ZIP files)
  • Mail archives (such as .PST files)
  • Forensic image files (such as .E01 files)

The upload API provides a way to reliably upload large files using chunked uploads. Client application uploads a file in parts, allowing it to recover from a failed requests. Thus, an application needs to retry the upload of a single chunk instead of the entire file. We also support uploading chunks concurrently.

Chunked uploads require a sequence of API calls to be made:

  1. Create an upload session
  2. Upload chunks
  3. Check upload status

Create upload session

Create a new upload session for a file.

When a session is created successfully the response includes a session id, allowed chunk size, and how many chunks can be uploaded concurrently.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)
Request Body schema: application/json
filename
required
string non-empty
fileSize
required
integer >= 0

File size in bytes

caseId
required
string (Id) [ 1 .. 500 ] characters

The resource identifier. The format varies for different resources.

description
string

This property can be used to store additional information about the upload for your own records. If not provided, it will be equal to filename.

fileModifiedAt
string <date-time>

Defines the time the file was last modified at. If not set, the upload time will be used.

Responses

Request samples

Content type
application/json
{
  • "filename": "index.zip",
  • "fileSize": 70609,
  • "caseId": "1",
  • "description": "Index archive for Test Case",
  • "fileModifiedAt": "2021-09-26T22:45:40.355Z"
}

Response samples

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

Upload file chunk

Upload a chunk of an upload session for a file.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)
path Parameters
id
required
string [ 1 .. 500 ] characters

The resource identifier string

Request Body schema: multipart/form-data
currentChunkNumber
required
integer >= 1

The index of the chunk in the current upload. First chunk is 1.

chunkSize
required
integer >= 0

The chunk size set during upload session creation. Note that the actual size of a chunk might be lower than this value for the last chunk.

totalFileSize
required
integer >= 0
totalNumberOfChunks
required
integer >= 1

The total number of chunks.

filename
required
string non-empty
file
required
string <binary>

Responses

Response samples

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

Check upload session status

Check upload session status.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)
path Parameters
id
required
string [ 1 .. 500 ] characters

The resource identifier string

Responses

Response samples

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

Cancel upload session

Cancel an upload session and discard all data uploaded.

This cannot be reversed.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)
path Parameters
id
required
string [ 1 .. 500 ] characters

The resource identifier string

Responses

Response samples

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

Case Hierarchy

APIs for managing case hierarchy, which is: Managing client > Client > Cases.

Retrieve a list of managing clients

Retrieve a list of all managing clients.

Authorizations:
bearerToken (
  • ipro.papi
  • ipro.api
  • ipro.superadmin
)

Responses

Response samples

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

Retrieve a managing client

Retrieve a managing client.