Evidence operations

Introduction

After having registered a "Case File" and an "Evidence Group", you can now create an "Evidence".

Operations

Create an "Evidence"

HTTP Request

POST /api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences

In this request, there is one primary resource case-files and a secondary one evidence-groups. There are also 2 resource identifiers that you need to replace with real values of your Legal App platform account: caseFileId and evidenceGroupId.

With the following information provided as JSON:

{
        "evidenceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "hash": "string",
        "createdBy": "example owner",
        "title": "example title",
        "type": "image/jpeg",
        "capturedAt": "2023-10-24T21:06:26.092Z",
        "custodyType": "INTERNAL",
        "fileName": "example.png",
        "fileSize": 1024,
        "testimony": {
          "additionalProp1": {
            "required": true,
            "providers": [
              "string"
            ]
          },
          "additionalProp2": {
            "required": true,
            "providers": [
              "string"
            ]
          },
          "additionalProp3": {
            "required": true,
            "providers": [
              "string"
            ]
          }
        },
        "requiredTestimonyProviders": [
          "EADTrust"
        ],
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "deletionDate": "2030-01-01T00:00:00Z",
        "deletionType": "FULL"
      }

Request body parameters

Parameter Mandatory Datatype Description
evidenceId yes UUID An identification for the "Evidence". UUID V4
hash yes string The hash(sha256) of the file of the "Evidence" in Hexadecimal.
createdBy no string(50) The owner of the "Evidence".
title no string The title of the "Evidence".
type no string Mime type of the "Evidence", e.g. image/jpeg
capturedAt yes datetime Date when the "Evidence" was captured
custodyType yes string(50) The type of custody. INTERNAL: The Legal Platform custodies the file. EXTERNAL: The Legal Platform DOES NOT custody the file.
fileName no string The file name of the "Evidence"
fileSize no integer The size in bytes of the file of the "Evidence"
testimony no object The testimony mode of the Evidence. It is optional because it is configured by tenant. Options: 
{
          "testimony": {
            "TSP": {
                "required": true,
                "providers": [
                    "EADTrust"
                ]
            },
            "DLT": {
                "required": true,
                "providers": [
                   "LACNet"
                ]
            }
         }
requiredTestimonyProviders no array of string List of testimony providers required for this "Evidence". Overwrites the tenant configuration when provided
metadata no object Metadata of the "Evidence"
deletionDate no datetime Date from which the "Evidence" will be scheduled for deletion. Requires deletionType when provided
deletionType no string Deletion type. Possible values: "FILE_ONLY" (delete file, keep evidence record) and "FULL" (delete file and mark evidence as deleted). Required when deletionDate is provided

When custodyType is INTERNAL, as response you will get the following JSON object with the upload URL for the file:

{
        "url": "http://example.io",
        "expiration": "2023-10-24T21:36:26.092Z"
            }

When custodyType is EXTERNAL, the response body is empty, since the Legal Platform does not custody the file.

Where:

HTTP Response parameters

Parameter Datatype Description
url string The URL to upload the file of the "Evidence"
expiration string Expiration of the url

Upload "Evidence" file

In case you have evidence with custodyType "INTERNAL" (We keep custody of the file), the URL that was returned to us in the previous endpoint must be used to upload the file.

As you can see in the following example, you have to enter the file hash in base64 and the file name: x-amz-checksum-sha256: here the file hash in base64 will go and then you have to enter the file name with extension.


  curl -v -H "x-amz-checksum-sha256: 3EMnNvppVhJqpPMcZPTtglG+3aNS4cWMrLzNEsToNUY=" -T "example.png" "https://<bucket>.s3.eu-west-1.amazonaws.com/<tenant>/evidences/29ef49f1-9259-41d8-b6d3-876f53e9f681/resource/example.png?X-Amz-Security-Token=<token>..."

Update "Evidences" (bulk)

To update the same field of several "Evidences" at once, you can send a list of patch operations that will be applied to all the given "Evidences". Currently only createdBy can be updated this way.

HTTP Request

PATCH /api/v1/private/evidences

With the following information provided as JSON:

{
        "ids": ["7e81750d-7906-43c9-bf6b-a9f30847c2e9", "1f7193a6-2454-4c67-8a64-b73c1049e92c"],
        "patch": [
          {
            "operation": "REPLACE",
            "path": "createdBy",
            "value": "example owner"
          }
        ]
      }

Request body parameters

Parameter Mandatory Datatype Description
ids yes array of UUID The identifiers of the "Evidences" to update. UUID V4
patch yes array of object List of patch operations to apply to all the given "Evidences". At most one operation per field.
patch[].operation yes string The patch operation. Possible values: "REPLACE" (set the field to the given value) and "REMOVE" (clear the field)
patch[].path yes string The field to update. Only "createdBy" is currently supported
patch[].value no string The new value of the field. Required for "REPLACE" operations, ignored for "REMOVE" operations.

As response, you will get 

204 Evidences updated correctly

If you need to update other fields (title, metadata, custody, deletionDate or deletionType) of a single "Evidence", see Update a single "Evidence".

Discard an "Evidence"

HTTP Request

DELETE /api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences/{evidenceId}

In this request, there is one primary resource case-files, a secondary one evidence-groups and a third one evidences. There are also 3 resource identifiers that you need to replace with real values of your Legal App platform account: caseFileId, evidenceGroupId and evidenceId.

As response, you will get 

204 "Evidence" discarded correctly

Get "Evidence" info

HTTP Request

GET /api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences/{evidenceId}

In this request, there is one primary resource case-files, a secondary one evidence-groups and a third one evidences. There are also 3 resource identifiers that you need to replace with real values of your Legal App platform account: caseFileId, evidenceGroupId and evidenceId.

And as response, we would get the following JSON object:

{
        "caseFileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "evidenceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "example title",
        "custodyType": "INTERNAL",
        "status": {
          "status": "COMPLETED",
          "tspTimestamp": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "dltTimestamp": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "file": "example.png"
        },
        "capturedAt": "2023-10-25T05:08:37.379Z",
        "fileName": "example.png",
        "fileSize": 1024,
        "hash": "string",
        "timestamps": {
          "tspTimestamps": {
            "additionalProp1": {
              "token": "string",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            },
            "additionalProp2": {
              "token": "string",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            },
            "additionalProp3": {
              "token": "string",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            }
          },
          "dltTimestamps": {
            "additionalProp1": {
              "blockHash": "string",
              "transactionHash": "string",
              "network": "string",
              "blockExplorerLink": "http://example.io",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            },
            "additionalProp2": {
              "blockHash": "string",
              "transactionHash": "string",
              "network": "string",
              "blockExplorerLink": "http://example.io",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            },
            "additionalProp3": {
              "blockHash": "string",
              "transactionHash": "string",
              "network": "string",
              "blockExplorerLink": "http://example.io",
              "timestampedAt": "2023-10-25T05:08:37.379Z"
            }
          }
        },
        "createdBy": "example owner",
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      }

Where:

HTTP Response parameters

Parameter Datatype Description
caseFileId UUID The identifier of the "Case file" to which the "Evidence Group" to which the "Evidence" belongs. UUID V4
groupId UUID The identifier of the "Evidence Group" to which the "Evidence" belongs. UUID V4
evidenceId UUID An identification for the "Evidence". UUID V4
title string Title of the "Evidence"
custodyType string(50) The type of custody. INTERNAL: The Legal Platform custodies the file. EXTERNAL: The Legal Platform DOES NOT custody the file.
status object Status of the "Evidence" and, if applicable, its timestamping processes. status.status possible values: "ERROR", "IN_PROCESS" and "COMPLETED". status.tspTimestamp and status.dltTimestamp are maps of provider name to timestamping process status. status.file is the internal custody file status, only present when custodyType is "INTERNAL"
capturedAt datetime Date when the "Evidence" was captured
fileName string The file name of the "Evidence"
fileSize integer The size in bytes of the file of the "Evidence"
hash string The hash (sha256) of the file of the "Evidence" in Hexadecimal
timestamps object Detail of the TSP and DLT timestamping processes of the "Evidence", keyed by provider name
createdBy string(50) The owner of the "Evidence".
metadata object Metadata of the "Evidence"

If the "Evidence" does not exist, or exists but does not belong to the given "Case file" or "Evidence Group", you will get a 404 Not found response.

Get "Evidence" list

HTTP Request

GET /api/v1/private/evidences

These call can be paged. This is specially usefull when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 200 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example:

GET /api/v1/private/evidences?page=0&size=25

With the following information provided as JSON:

{
        "id": "[3fa85f64-5717-4562-b3fc-2c963f66afa6, c3a8eb1c-3f6d-4bad-9e6b-c7e29461d021]",
        "caseFileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "groupId": "[3fa85f64-5717-4562-b3fc-2c963f66afa6, c3a8eb1c-3f6d-4bad-9e6b-c7e29461d021]",
        "groupType": "FILE",
        "title": "example title",
        "hash": "string",
        "custodyType": "INTERNAL",
        "testimonyMode": "DLT",
        "status": "COMPLETED",
        "fileName": "example.png",
        "fileSize": 1024,
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "capturedFrom": "2023-10-25T05:19:12.468Z",
        "capturedUntil": "2023-10-25T05:19:12.468Z",
        "collectionMetadata": true,
        "page": 0,
        "size": 0,
        "sort": "[\"groupName:ASC\", \"capturedAt:DESC\"]"
      }

As response, you will get the following JSON object:

{
        "_metadata": {
          "currentPage": 0,
          "totalPages": 0,
          "pageSize": 0,
          "totalRecords": 0
        },
        "records": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "caseFileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "group": {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "name": "example name",
              "type": "FILE",
              "code": "example code"
            },
            "title": "example title",
            "hash": "string",
            "fileSize": 1024,
            "custodyType": "INTERNAL",
            "createdBy": "example owner",
            "capturedAt": "2023-10-25T05:20:17.926Z",
            "fileName": "example.png",
            "status": {
              "status": "COMPLETED",
              "tspTimestamp": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
              },
              "dltTimestamp": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
              },
              "file": "example.png"
            },
            "timestamps": {
              "tspTimestamps": {
                "additionalProp1": {
                  "token": "string",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                },
                "additionalProp2": {
                  "token": "string",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                },
                "additionalProp3": {
                  "token": "string",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                }
              },
              "dltTimestamps": {
                "additionalProp1": {
                  "blockHash": "string",
                  "transactionHash": "string",
                  "network": "string",
                  "blockExplorerLink": "http://example.io",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                },
                "additionalProp2": {
                  "blockHash": "string",
                  "transactionHash": "string",
                  "network": "string",
                  "blockExplorerLink": "http://example.io",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                },
                "additionalProp3": {
                  "blockHash": "string",
                  "transactionHash": "string",
                  "network": "string",
                  "blockExplorerLink": "http://example.io",
                  "timestampedAt": "2023-10-25T05:20:17.926Z"
                }
              }
            },
            "metadata": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            }
          }
        ]
      }

Where:

HTTP Response parameters

Parameter Datatype Description
fileSize int The size in bytes of the file of the "Evidence"
timestamps object The detail of the timestampings processes.

Create Download URL

HTTP Request

GET /api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences/{evidenceId}/download-url

In this request, there is one primary resource case-files, a secondary one evidence-groups and a third one evidences. There are also 3 resource identifiers that you need to replace with real values of your Legal App platform account: caseFileId, evidenceGroupId and evidenceId.

As response, you will get the following JSON object:

{
"url": "http://example.io",
"expiration": "2023-10-24T21:36:26.092Z"
}

Where:

HTTP Response parameters

Parameter Datatype Description
url string The URL to download the file of the "Evidence"
expiration string Expiration of the url

Create Upload URL

HTTP Request

POST /api/v1/private/case-files/{caseFileId}/evidence-groups/{evidenceGroupId}/evidences/{evidenceId}/upload-url

In this request, there is one primary resource case-files, a secondary one evidence-groups and a third one evidences. There are also 3 resource identifiers that you need to replace with real values of your Legal App platform account: caseFileId, evidenceGroupId and evidenceId.

With the following information provided as JSON:

{
  "fileName": "example.pdf"
}

Request body parameters

Parameter Mandatory Datatype Description
fileName yes string Filename of "Evidence". String

As response, you will get the following JSON object:

{
 "url": "http://example.io",
 "expiration": "2023-10-24T21:36:26.092Z"
}

Where:

HTTP Response parameters

Parameter Datatype Description
url string The URL to upload the file of the "Evidence"
expiration string Expiration of the url

Evidence operations without a "Case file" / "Evidence Group"

Every operation above can also be performed on an "Evidence" that is registered directly, without nesting it under a "Case file" and "Evidence Group". These flat operations use the same request and response bodies as their nested counterparts.

Create an "Evidence" (without a group)

HTTP Request

POST /api/v1/private/evidences

The request body and response are the same as in Create an "Evidence".

As response, you will get 

201 "Evidence" created

Get "Evidence" info (without a group)

HTTP Request

GET /api/v1/private/evidences/{evidenceId}

The response is the same as in Get "Evidence" info, except that caseFileId and groupId will not be present.

If the "Evidence" does not exist, you will get a 404 Not found response.

Update a single "Evidence"

To update the information of a single "Evidence" you can make the following request using the id of the "Evidence".

HTTP Request

PATCH /api/v1/private/evidences/{evidenceId}

With the following information provided as JSON:

{
        "title": "example title",
        "createdBy": "example owner",
        "metadata": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "custody": "INTERNAL",
        "deletionDate": "2030-01-01T00:00:00Z",
        "deletionType": "FULL"
      }

If you only want to update one of the fields you only have to send this one in the request. To cancel a scheduled deletion, send deletionDate: null.

Request body parameters

Parameter Mandatory Datatype Description
title no string The new title of the "Evidence"
createdBy no string(50) The new owner of the "Evidence"
metadata no object New metadata of the "Evidence"
custody no string The new custody type. Possible values: "INTERNAL" and "EXTERNAL"
deletionDate no datetime Date from which the "Evidence" will be scheduled for deletion. Set to null to cancel a scheduled deletion
deletionType no string Deletion type. Possible values: "FILE_ONLY" and "FULL". Required when deletionDate is provided with a non-null value

As response, you will get 

204 Evidence updated

If the "Evidence" does not exist, you will get a 404 Not found response. If the deletionDate violates the minimum configured deletion threshold, you will get a 422 Unprocessable Entity response.

Discard an "Evidence" (without a group)

HTTP Request

DELETE /api/v1/private/evidences/{evidenceId}

As response, you will get 

204 "Evidence" discarded correctly

If the "Evidence" does not exist, you will get a 404 Not found response.

Create Download URL (without a group)

HTTP Request

GET /api/v1/private/evidences/{evidenceId}/download-url

The response is the same as in Create Download URL.

Create Upload URL (without a group)

HTTP Request

POST /api/v1/private/evidences/{evidenceId}/upload-url

The request body and response are the same as in Create Upload URL.

If you want to try any of these functionalities yourself and learn more about them, please go to the API catalogue