Evidence operations
Contents
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 EADFactory 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 | depends | string | The file name of the "Evidence". Mandatory when custodyType is
INTERNAL: without it the request fails with a 400 and the code
#MESSAGE_FILENAME_MANDATORY#. Optional when it is EXTERNAL |
| fileSize | no | integer | The size in bytes of the file of the "Evidence" |
| testimony | yes | object | Mandatory in practice. The tenant defaults are not applied if you leave it out, and an
empty list is rejected with a 400. Only TSP timestamping is
available today: asking for a DLT provider comes back as a 400 with
#PROVIDER_NOT_CONFIGURED#.
Options:
|
| 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 EADFactory 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 EADFactory 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 EADFactory 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 EADFactory account:
caseFileId, evidenceGroupId and evidenceId.
With the following information provided as JSON:
{
"requestModel": {
"fileName": "example.pdf"
}
}
This route wraps the body in requestModel. The flat route
POST /api/v1/private/evidences/{evidenceId}/upload-url takes the same field
without the wrapper. They are not interchangeable: sending one shape to the other route
fails.
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 response is the same as in Create Upload URL. The request body is not. This route takes the field directly, with no wrapper:
{
"fileName": "example.pdf"
}
Get the thumbnail of an "Evidence"
For evidences that are images, the platform generates thumbnails. This returns a pre-signed URL for one of them, in the size you ask for.
HTTP Request
GET /api/v1/private/case-files/{caseFileId}/evidence-groups/{groupId}/evidences/{evidenceId}/thumbnail-url/{thumbnailSize}
Where thumbnailSize is one of SMALL, REGULAR or
BIG.
As response, you will get the URL and its expiration:
{
"url": "http://example.io",
"expiration": "2023-10-24T21:36:26.092Z"
}
Not every evidence has a thumbnail, and that is not a failure on your side. They are only
generated for images, and for some files the generation does not succeed. Treat a 404
here as "there is no thumbnail", not as an error to retry.
Note that this route names the group groupId, while its neighbours call the same value
evidenceGroupId.
Upload a large file (multipart)
The single pre-signed URL works for normal files. For large ones, such as video, use the multipart flow: four calls instead of one.
1. Start the upload
POST /api/v1/private/uploads/{evidenceId}/{fileName}
Returns the uploadId that identifies this upload.
2. Get a link for each part
GET /api/v1/private/uploads/{evidenceId}/{filename}/{uploadId}?partNumber=1
Call it once per part, and upload each part to the link it returns.
3. Complete the upload
POST /api/v1/private/uploads/{evidenceId}/{filename}/{uploadId}?partsCount=3
4. Cancel it, if you give up
DELETE /api/v1/private/uploads/{evidenceId}/{filename}/{uploadId}
Without step 3 the file does not exist, no matter how many parts you uploaded. And if you abandon an upload, call step 4: unfinished parts stay there taking up space.
Watch the spelling of the path: step 1 uses {fileName} and the other three use
{filename}. It is the same value.
Create an "Evidence" and its upload URL in one call
The flow above needs you to register the "Evidence" first and ask for the upload link afterwards, and registering it requires the file hash. This route does both things at once and does not ask for a hash, so it is the way in when you cannot compute the SHA-256 before uploading, for example when the file is being streamed or produced on the fly.
HTTP Request
POST /api/v1/private/files
With the following information provided as JSON:
{
"evidenceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Signed contract",
"fileName": "contract.pdf",
"createdBy": "integration-service",
"capturedAt": "2026-09-17T10:15:00Z",
"testimony": {
"TSP": {
"required": true,
"providers": ["EADTrust"]
}
},
"caseFileId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
"evidenceGroupId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
Request body parameters
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| evidenceId | yes | UUID | The identifier you choose for the "Evidence". UUID V4 |
| title | yes | string | The title of the "Evidence" |
| fileName | yes | string | The file name of the "Evidence" |
| createdBy | yes | string | Who is registering the "Evidence" |
| capturedAt | yes | date-time | When the evidence was captured |
| testimony | yes | object | The testimony mode, as in Create an "Evidence". Only
TSP is available today |
| caseFileId | no | UUID | The "Case file" it belongs to |
| evidenceGroupId | no | UUID | The "Evidence group" it belongs to |
| metadata | no | object | Free key and value pairs |
As response, you will get the upload link, with the same shape as the other upload routes:
{
"url": "http://example.io",
"expiration": "2023-10-24T21:36:26.092Z"
}
This one answers 200, while the other upload routes answer 201.
Uploading to the returned link still requires the x-amz-checksum-sha256 header, in
base64. Not asking for the hash up front does not mean the upload skips the integrity check.
If you want to try any of these functionalities yourself and learn more about them, please go to the API catalogue