Case Management
This document details the operation and usage of endpoints for managing cases in the Certificall application.
Case Search
Endpoint: GET /cases
Description
The case search endpoint allows authenticated users to query and retrieve cases registered in the Certificall system, applying various filters to refine results according to specific needs.
Authentication
Access to this endpoint requires valid authentication. Include a JWT (JSON Web Token) in the header of your HTTP request as follows:
Authorization: Bearer <Your_JWT_Token>
HTTP Request
Method: GET
URL: /cases
Query Parameters
General filters
- reportToken (String, optional): Report token associated with the cases being searched.
- companyId (Number, optional): Identifier of the company associated with the cases.
- frameId (Number, optional): Identifier of the frame used for the cases.
- caseId (Number, optional): Identifier of the case being searched.
- withReportToken (Boolean, optional): Indicates whether the report token should be included in the results.
- closed (Boolean, optional): Filters by status. Accepted values:
true(closed cases only) orfalse(open cases only). If the parameter is absent or does not match a valid boolean, the endpoint returns both open AND closed cases. - format (Enum, required): Specifies the response format (
zipormetadata).
Time window (filter on createdAt)
Three mutually exclusive modes:
- hours (Number, optional): Relative window — number of hours in the past from now. Max 168 (1 week), default 12 hours.
- startDate (String, optional): Absolute lower bound (inclusive). Accepted: ISO 8601 with timezone (
"2026-04-23T08:00:00+02:00") or date only ("2026-04-23", read as midnight UTC). - endDate (String, optional): Absolute upper bound (inclusive). Same formats. A date only is extended to the end of the UTC day (
23:59:59.999). An ISO datetime exactly equal to midnight UTC is treated as a date only.
⚠️
hoursandstartDate/endDateare mutually exclusive (400 if both are supplied).Maximum range between
startDateandendDate: 7 days (400 if exceeded).
Pagination
Pagination is opt-in: without limit or offset, the endpoint returns every matched case (legacy behaviour). Pagination starts as soon as either one is supplied.
- limit (Number, optional): Maximum number of cases returned. Default:
50, max:100. - offset (Number, optional): Number of cases to skip. Default:
0.
The total number of matched cases is exposed in the X-Total-Count HTTP response header (always present, even without explicit pagination). Iterate by increasing offset by limit until you receive 0 cases.
Note:
limitandoffsetalso apply to thezipformat. To export more thanlimitcases as ZIP, iterate over several paginated requests.
Example:
curl -X 'GET' \
'https://admin.certificall.app/certificall/api/cases?format=metadata&hours=48' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
Responses
200 OK: Returns a list of cases matching the specified criteria.
Response example for a request with format=metadata:
[
{
"id": 12345,
"cfRef": "REF123",
"closingDate": "2023-01-01T00:00:00Z",
"createdAt": "2022-12-01T00:00:00Z",
"scheduledAt": "2026-06-15T00:00:00.000Z",
"closed": true,
"frame": "Frame A",
"companyName": "Company XYZ",
"reportId": "TOKEN123",
"caseUrl": "https://certificall.example.com/download/SHARETOKEN123",
"metadata": { "site": "Paris", "zone": "A1" }
}
]
id(number): internal numeric identifier of the case, used by subsequent operations (/cases/:caseId,/cases/close/:caseId,/cases/delete/:caseId).cfRef(string): public identifier in theCAS-XXXX_CMP-Yformat.
metadata(object): the case's free-form metadata, exactly as supplied on creation — through themetadatafield ofPOST /cases/create, a Certilink or the mobile SDK. The key is absent from cases that carry none. It does not look a case up (usereportToken), but it filters consumption.
scheduledAt(ISO 8601 string | null): date from which the case becomes visible in the mobile app.nullif the case is not scheduled.
400 Bad Request: The request is invalid, usually due to missing or incorrect parameters.
500 Internal Server Error: Internal server error preventing request processing.
Practical example
Get the id of today's open cases created between 6am and 11am
Combine startDate + endDate (absolute window with timezone) + closed=false, and extract the id with jq:
TODAY=$(date +%Y-%m-%d)
curl -s -X 'GET' \
"https://admin.certificall.app/certificall/api/cases?format=metadata&startDate=${TODAY}T06:00:00%2B02:00&endDate=${TODAY}T11:00:00%2B02:00&closed=false" \
-H "Authorization: Bearer ${TOKEN}" \
| jq -r '.[].id'
Expected output (one id per line):
4582
4581
4576
For a richer output (id + cfRef + creation time):
... | jq -r '.[] | "\(.id)\t\(.cfRef)\t\(.createdAt)"'
Notes:
%2B02:00is the URL encoding of+02:00(Europe/Paris timezone). Adapt it to your timezone.- To check the available total before iterating, read the
X-Total-Countheader:curl -sI -H "Authorization: Bearer ${TOKEN}" "<same URL>" | grep -i x-total-count - If you expect more than 50 cases, add
&limit=100&offset=0and iterate by increasingoffset.
Retrieving a Case
Endpoint: GET /cases/:caseId
Description
Returns a full case from its identifier: its details, its items (in the same order as on the PDF certificate) and, if it has one, its score.
The score (scoring) comes from the frame's scoring scale. It is unrelated to the trust level (trustScore) returned by the case analysis.
Request
-
URL:
/cases/:caseId -
HTTP Method:
GET -
Path parameters:
caseId:number— Case identifier (idreturned byPOST /cases/createorGET /cases).
-
Required headers:
Authorization: Bearer <Your_JWT_Token>
Required Permissions
- Permission API > File > Consult.
- The case must belong to your company, to one of its subsidiaries, or to a supervised frame that you own.
Example
curl -X GET \
"https://admin.certificall.app/certificall/api/cases/4582" \
-H "Authorization: Bearer your_jwt_token"
Successful response
Status: 200 OK
{
"id": 4582,
"cfRef": "CAS-4582_CMP-12",
"title": "Compliance visit",
"createdAt": "2026-05-15T08:12:40.000Z",
"scheduledAt": null,
"reportId": "TOKEN123",
"frame": "Frame A",
"caseUrl": "https://admin.certificall.app/certificall/share/case/SHARETOKEN123",
"closed": true,
"closingDate": "2026-05-15T09:03:11.000Z",
"companyName": "Company XYZ",
"metadata": { "site": "Paris", "zone": "A1" },
"scoring": {
"total": 19,
"elements": [
{ "elementType": "step", "elementId": 3305, "title": "Severity", "parentGroupId": 20, "points": -6 },
{ "elementType": "step", "elementId": 3306, "title": "Site access", "parentGroupId": 20, "points": 25 },
{ "elementType": "group", "elementId": 20, "title": "Diagnosis", "parentGroupId": null, "points": 19 }
]
},
"items": [
{
"createdAt": "2026-05-15T08:20:02.000Z",
"cfRef": "ITM-98765",
"description": "",
"data": "",
"geolocLatitude": "48.8566",
"geolocLongitude": "2.3522",
"imageUrl": "https://admin.certificall.app/certificall/images/...",
"stepAction": "PHOTOGRAPHY",
"stepTitle": "Front of the building",
"stepDescription": "Capture the whole front",
"imageHash": "3f8a…",
"tspTokenHash": "9c1e…"
}
]
}
Data model
The case
| Field | Type | Description |
|---|---|---|
id | Number | Numeric identifier of the case. |
cfRef | String | Public identifier in the CAS-XXXX_CMP-Y format. |
title | String | Case title. Absent from cases opened through Certilink or the SDK, which carry a reference (reportId) instead. |
createdAt | String (ISO 8601) | Creation date. |
scheduledAt | String (ISO 8601) | null | Scheduled date, null if the case is not scheduled. |
reportId | String | Token of the associated report. |
frame | String | Frame name. |
caseUrl | String | null | Share link of the case (see Share Token), null if the case is not shared. |
closed | Boolean | true if the case is closed. |
closingDate | String (ISO 8601) | Closing date. |
companyName | String | Name of the case's company. |
metadata | Object | Free-form metadata supplied on creation. Absent if the case carries none. |
scoring | Object | Case score (see below). Absent if the case has no score. |
items | Array | Collected data, in the order of the PDF certificate (see below). |
scoring — case score
| Field | Type | Description |
|---|---|---|
total | Number | Case total: the sum of the steps' points. |
elements | Array | Every scored step, then the subtotal of every group. A step without an answer is not listed. |
elements[].elementType | String | step or group. |
elements[].elementId | Number | Identifier of the step or group (see GET /frames). |
elements[].title | String | Step title or group name in the current frame. Absent if the element has since been removed from the frame. |
elements[].parentGroupId | Number | null | Group containing the element: a step's group, a subgroup's parent group. null at the root of the frame. Absent if the element has since been removed from the frame. |
elements[].points | Number | Step: points it adds to the total (can be negative). Group: subtotal of its steps. |
A group's subtotal is already counted through its steps. Do not add it to the total: total is the sum of the steps alone.
The score is computed by the mobile app during data entry and saved when the case is closed. The scoring key is therefore absent from:
- a case closed through the API or the SDK;
- a case that is still open;
- a case whose frame has no scoring scale.
An absent score is not a total of 0: a case can genuinely score 0.
items — collected data
| Field | Type | Description |
|---|---|---|
createdAt | String (ISO 8601) | Item creation date. |
cfRef | String | Item reference. |
data | String | Entered value (text, selection, date…). |
description | String | Same value as data. |
geolocLatitude / geolocLongitude | String | Position at collection time. |
imageUrl | String | Link to the media for a photo or a video (see Media), empty string otherwise. |
stepAction | String | Step type: PHOTOGRAPHY, VIDEO, SIGNATURE, DOCUMENT_UPLOAD, TEXT_FIELD, SELECT, DATE_FIELD, TIME, EMAIL or NUMBER_FIELD. |
stepTitle / stepDescription | String | Step title and instructions. |
imageHash | String | Hash of the timestamped file, if the item has one. |
tspTokenHash | String | Hash of the qualified timestamp token, if the item has one. |
extractedData | Array | Fields extracted by document analysis: key, label, value. Absent if none. |
Error responses
| Status | Description |
|---|---|
403 Forbidden | The case does not belong to your company, to one of its subsidiaries, or to a supervised frame that you own. |
404 Not Found | No case has this identifier. |
Case Creation
Endpoint: POST /cases/create
Description
This API endpoint allows authenticated users to create a new case in the Certificall system. The case can be associated with a specific user or a certilink (Magic Link) for use without authentication.
Authentication
Access to this endpoint requires valid authentication. Include a JWT (JSON Web Token) in the header of your HTTP request as follows:
Authorization: Bearer <Your_JWT_Token>
HTTP Request
Method: POST
URL: /cases/create
Request Body (Payload)
Required parameter:
frameId(Number): Identifier of the frame to use for the case.
Optional parameters:
title(String): Case title.userId(String): Keycloak identifier of the user to associate with the case (exclusive withmagicLinkToken).childCompanyId(Number): ID of the target child company (used only with certilink).magicLinkToken(String): Token of an existing certilink to use (exclusive withuserId).certilinkOptions(Object): Options to automatically create a new certilink.reportToken(String, required): Unique report token for the certilink.maxUses(Number, optional): Maximum number of authorized uses.expirationDate(String, optional): Expiration date (format:yyyy-mm-ddThh:mm:ss.sss+hhmm).
reportToken(String): Report token to associate or create a report.caseContext(Object): Case context (visible data).visibleData(Object): Data visible in the case.beneficiary(Object): Beneficiary information.lastName(String): Last name.firstName(String): First name.address(String): Address.city(String): City.postCode(String): Postal code.email(String): Email address.
issuer(String): Case issuer.photoRef(String): Photo reference.reportRef(String): Report reference.instructions(String): Specific instructions for the user.user(String): User name to display in the PDF.
metadata(Object, optional): the case's free-form metadata, string key-value pairs (20 keys max, 40 characters per key, 500 per value). Returned with the case inGET /casesand in the case webhook.
Request Examples
Example 1: Create a case for a specific user
{
"frameId": 10,
"title": "Technical inspection",
"userId": "user-keycloak-id-123",
"reportToken": "REPORT-2024-001",
"caseContext": {
"visibleData": {
"beneficiary": {
"lastName": "Dupont",
"firstName": "Jean",
"email": "jean.dupont@example.com"
},
"issuer": "ACME Company",
"instructions": "Check the general condition of the equipment"
}
},
"metadata": {
"source": "api",
"version": "1.0"
}
}
Example 2: Create a case with an automatic certilink
{
"frameId": 10,
"title": "External inspection",
"certilinkOptions": {
"reportToken": "REPORT-2024-002",
"maxUses": 5,
"expirationDate": "2025-12-31T23:59:59.000+0100"
},
"caseContext": {
"visibleData": {
"beneficiary": {
"lastName": "Martin",
"firstName": "Sophie",
"address": "123 Rue de la Paix",
"city": "Paris",
"postCode": "75001",
"email": "sophie.martin@example.com"
},
"instructions": "Please note the apartment number"
}
}
}
Example 3: Create a case with an existing certilink
{
"frameId": 10,
"magicLinkToken": "09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
"title": "Scheduled inspection",
"caseContext": {
"visibleData": {
"issuer": "ABC Company",
"instructions": "Follow the standard protocol"
}
}
}
Responses
Successful response:
- Status:
201 Created - Description: The case has been created successfully.
- Response example:
{
"id": 12345,
"cfRef": "CAS-12345_CMP-1",
"frameId": 10,
"title": "Technical inspection",
"createdAt": "2024-01-15T10:30:00Z",
"closed": false,
"magicLinkUrl": "https://app.certificall.app/?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
}
Error response:
-
Status:
400 Bad Request -
Description: The request is invalid (missing or incorrect parameters).
{
"statusCode": 400,
"message": "frameId is required",
"error": "Bad Request"
} -
Status:
403 Forbidden -
Description: You do not have the necessary permissions to create a case.
-
Status:
404 Not Found -
Description: The specified frame does not exist or does not belong to your company.
Required Permissions
- The user must have the API > File > Create permission.
- The frame must belong to your company or be accessible.
Use Cases
Use this endpoint to:
- Create a case intended for a specific user on your team
- Generate a case accessible via a certilink (Magic Link) for external users
- Initialize a case with pre-filled information (beneficiary, instructions, etc.)
- Create a case and a certilink in a single operation
Important Notes
userIdandmagicLinkTokenare mutually exclusive: you must use one or the other, but not both.- If you use
certilinkOptions, a new certilink will be automatically created for this case. - The
reportTokenfield incertilinkOptionsis required if you use this option. - Metadata must be key-value pairs with string-type values.
Do not call this endpoint in a loop: you would quickly hit the rate limit and get a 429. Use bulk create below, which counts as a single request.
Bulk Create
Endpoint: POST /cases/bulk-create
Creates several cases in a single request. Designed for integrations that need to open a set of cases at once — for instance one case per intervention on the same site.
Only one call is counted, whatever the size of the array. This endpoint has its own rate limit of 10 requests per minute — up to 500 cases created per minute, against 60 when looping on the single creation.
Request
POST /certificall/api/cases/bulk-create
Authorization: Bearer <Your_JWT_Token>
Content-Type: application/json
The body is an array of objects, each in the same format as the single creation (POST /cases/create):
[
{ "frameId": 10, "title": "Intervention batch A", "userMail": "technician@example.com" },
{ "frameId": 10, "title": "Intervention batch B", "userMail": "technician@example.com" },
{ "frameId": 12, "title": "Final check" }
]
Limit: 50 cases per request. Beyond that the API responds 400 — split your processing into several calls.
Two identical lines in the array create two distinct cases. Before resending an interrupted request (network failure, timeout), check with GET /cases which cases were already created.
Required Permissions
Two permissions are required:
| Permission (in the admin) | Purpose |
|---|---|
| API > File > Create | Creating a case |
| API > File > Bulk create | Access to bulk create |
If either is missing, the API responds 403 and no case is created.
Response
Status code: 200 OK, even if some cases fail. Each case is created independently: one failure does not cancel the others, and cases already created are kept.
{
"state": "Cases bulk create ended",
"date": "2026-09-15T09:12:34.567Z",
"company": 42,
"success": [
{ "index": 0, "caseId": 12345 },
{ "index": 2, "caseId": 12346 }
],
"error": [
{ "index": 1, "error": "Error while creating case" }
]
}
| Field | Description |
|---|---|
success | Cases actually created |
error | Lines not created, each with its reason |
index | Position in the array you sent |
caseId | Identifier assigned to the created case. Absent from error entries, since the case does not exist |
error arrayA 200 does not mean every case was created. Walk through error to find the lines to fix and resend.
Processing order is not guaranteed: rely on index to match each caseId with the corresponding line of your request. Only the identifier is returned; to get the details of a created case, use GET /cases with the caseId parameter.
The failure reason is the one returned by the business service (frame not found, unknown user…) or, by default, Error while creating case. These labels are not guaranteed to be stable: route your errors on a line being present in error[] rather than on the exact wording.
Request errors
In these cases, no case is created:
| Status | Context |
|---|---|
400 | Empty array, more than 50 cases, or invalid element. Errors for every element are returned, prefixed with their position: [1] frameId must be a number conforming to the specified constraints |
403 | One of the two required permissions is missing |
429 | Rate limit of 10 requests per minute exceeded on this endpoint |
Closing a Case
Endpoint: GET /cases/close/:caseId
Description
This API endpoint allows users to close an ongoing case. Once closed, the case is considered finalized and can no longer be modified. This action is essential to indicate the end of the data collection process.
Request
-
URL:
/cases/close/:caseId -
HTTP Method:
GET -
Path parameters:
caseId:number- The unique identifier of the case to close.
-
Required headers:
Authorization: Bearer <Your_JWT_Token>
Responses
Successful response:
- Status:
200 OK - Description: The case has been closed successfully.
- Response example:
{
"status": "Success",
"message": "Case closed successfully"
}
Error response:
-
Status:
400 Bad Request -
Description: The request is invalid or the case does not exist.
{
"statusCode": 400,
"message": "Invalid case ID",
"error": "Bad Request"
} -
Status:
403 Forbidden -
Description: You do not have the necessary permissions or the case does not belong to your company.
Required Permissions
- The case must belong to your company to be closed.
Use Cases
Use this endpoint when you have finished collecting all necessary data for a case and want to finalize it. Once closed, the case can no longer receive new items.
Updating a Case
Endpoint: PATCH /cases/update
Description
This API endpoint allows users to update information of an existing case. You can modify the title, associated frame, user, report token, or case context.
Request
-
URL:
/cases/update -
HTTP Method:
PATCH -
Required headers:
Authorization: Bearer <Your_JWT_Token>
Content-Type: application/json
Request Body (Payload)
caseId(Number, required): Identifier of the case to update.title(String, optional): New case title (maximum 255 characters).frameId(Number, optional): Identifier of the new frame to associate.userId(String, optional): Keycloak identifier of the user to associate.reportToken(String, optional): Report token to associate with the case.caseContext(Object, optional): Case context (visible data).visibleData(Object, optional): Data visible in the case.beneficiary(Object, optional): Beneficiary information.lastName(String): Last name.firstName(String): First name.address(String): Address.city(String): City.postCode(String): Postal code.email(String): Email address.
issuer(String): Case issuer.photoRef(String): Photo reference.reportRef(String): Report reference.instructions(String): Specific instructions.user(String): User name to display.
metadata(Object, optional): the case's free-form metadata, string key-value pairs (20 keys max, 40 characters per key, 500 per value). Replaces the case's current metadata;nullclears it. Returned inGET /casesand in the case webhook.
Request body example:
{
"caseId": 12345,
"title": "Updated inspection",
"reportToken": "REPORT-2024-001",
"caseContext": {
"visibleData": {
"beneficiary": {
"lastName": "Dupont",
"firstName": "Jean",
"email": "jean.dupont@example.com"
},
"issuer": "ACME Company",
"instructions": "Check the general condition of the equipment"
}
},
"metadata": {
"source": "api",
"version": "2.0"
}
}
Responses
Successful response:
- Status Code: 200 OK
- Description: The case has been updated successfully.
Successful response example:
{
"success": true
}
Error response:
-
Status Code: 400 Bad Request
-
Description: The request is invalid (missing or incorrect parameters).
-
Status Code: 403 Forbidden
-
Description: You do not have the necessary permissions or the case does not belong to your company.
-
Status Code: 404 Not Found
-
Description: The specified case does not exist.
Required Permissions
- The case must belong to your company to be updated.
Use Cases
Use this endpoint to:
- Correct a case title
- Modify beneficiary information
- Associate a new report token
- Add or modify metadata
- Change the frame associated with the case
Do not call this endpoint in a loop: you would quickly hit the rate limit and get a 429. Use bulk update below, which counts as a single request.
Bulk Update
Endpoint: PATCH /cases/bulk-update
Updates several cases in a single request. Designed for integrations that need to propagate the same information across a set of related cases — for instance reflecting a date change on every case attached to the same deal.
Only one call is counted, whatever the size of the array. This endpoint has its own rate limit of 10 requests per minute — up to 1000 cases updated per minute, against 60 when looping on the single update.
Request
PATCH /certificall/api/cases/bulk-update
Authorization: Bearer <Your_JWT_Token>
Content-Type: application/json
The body is an array of objects, each in the same format as the single update:
[
{ "caseId": 12345, "scheduledAt": "2026-09-10T09:00:00+02:00" },
{ "caseId": 12346, "scheduledAt": "2026-09-10T09:00:00+02:00" },
{ "caseId": 12347, "scheduledAt": "2026-09-10T09:00:00+02:00" }
]
Limit: 100 cases per request. Beyond that the API responds 400 — split your processing into several calls.
Required Permissions
Two permissions are required:
| Permission (in the admin) | Purpose |
|---|---|
| API > File > Update | Updating a case |
| API > File > Bulk update | Access to bulk update |
If either is missing, the API responds 403 and no case is processed.
Response
Status code: 200 OK, even if some cases fail. Each case is processed independently: one failure does not cancel the others.
{
"state": "Cases bulk update ended",
"date": "2026-08-13T09:12:34.567Z",
"company": 42,
"success": [
{ "index": 0, "caseId": 12345 },
{ "index": 2, "caseId": 12347 }
],
"error": [
{ "index": 1, "caseId": 12346, "error": "case.notBelongCompany" }
]
}
| Field | Description |
|---|---|
success | Cases actually updated |
error | Failed cases, each with its reason |
index | Position in the array you sent |
caseId | Identifier of the case concerned |
error arrayA 200 does not mean every case was updated. Walk through error to find which ones failed and why.
Processing order is not guaranteed: do not rely on the position within success or error, but on the index field, which points back to the original position in your request.
Common failure reasons
| Message | Cause |
|---|---|
case.notBelongCompany | The case belongs to another company |
case.scheduledAt.mustBeCurrentOrFutureMonth | The scheduled date is earlier than the current month |
case.scheduledAt.invalid | Unrecognised date format |
Error while updating case | The case does not exist, or the business service is temporarily unavailable |
These labels come from the business service and are not guaranteed to be stable. To route your errors, rely on a case being present in error[] rather than on the exact wording.
Deleting a Case
Endpoint: DELETE /cases/delete/:caseId
Description
This API endpoint allows users to permanently delete a case from the system. This action is irreversible and deletes all data associated with the case.
Request
-
URL:
/cases/delete/:caseId -
HTTP Method:
DELETE -
Path parameters:
caseId:number- The unique identifier of the case to delete.
-
Required headers:
Authorization: Bearer <Your_JWT_Token>
Responses
Successful response:
- Status:
200 OK - Description: The case has been deleted successfully.
- Response example:
{
"status": "Success",
"message": "Case deleted successfully"
}
Error response:
-
Status:
400 Bad Request -
Description: The request is invalid or the case does not exist.
-
Status:
403 Forbidden -
Description: You do not have the necessary permissions or the case does not belong to your company.
Required Permissions
- The case must belong to your company to be deleted.
Warning
WARNING: This operation is irreversible. Once the case is deleted, all associated data (items, photos, videos, metadata) will be permanently lost.
Use Cases
Use this endpoint only when you need to permanently delete a case, for example:
- Case created by mistake
- Erroneous data that requires complete deletion
- Compliance with data retention policies
Do not call this endpoint in a loop: you would quickly hit the rate limit and get a 429. Use bulk delete below, which counts as a single request.
Bulk Delete
Endpoint: POST /cases/bulk-delete
Deletes several cases in a single request. Each case is deleted exactly as with the single deletion.
Only one call is counted, whatever the size of the array. This endpoint has its own rate limit of 10 requests per minute — up to 500 cases deleted per minute, against 60 when looping on the single deletion.
Request
POST /certificall/api/cases/bulk-delete
Authorization: Bearer <Your_JWT_Token>
Content-Type: application/json
The body is an object holding the list of identifiers to delete:
{
"caseIds": [12345, 12346, 12347]
}
POST and not DELETE?Many HTTP clients and proxies handle a request body on DELETE poorly. POST guarantees that the list of cases reaches the API intact.
Limit: 50 cases per request, with no duplicates. Beyond that the API responds 400 — split your processing into several calls.
As with the single deletion, all data associated with the deleted cases (items, photos, videos, metadata) is permanently lost. Double-check the list of identifiers before sending it.
Required Permissions
Two permissions are required:
| Permission (in the admin) | Purpose |
|---|---|
| API > File > Delete | Deleting a case |
| API > File > Bulk delete | Access to bulk delete |
If either is missing, the API responds 403 and no case is deleted.
Response
Status code: 200 OK, even if some cases fail. Each case is processed independently: one failure does not cancel the others.
{
"state": "Cases bulk delete ended",
"date": "2026-09-15T09:12:34.567Z",
"company": 42,
"success": [
{ "index": 0, "caseId": 12345 },
{ "index": 2, "caseId": 12347 }
],
"error": [
{ "index": 1, "caseId": 12346, "error": "Error while deleting case" }
]
}
| Field | Description |
|---|---|
success | Cases actually deleted |
error | Failed cases, each with its reason |
index | Position in the caseIds array you sent |
caseId | Identifier of the case concerned |
error arrayA 200 does not mean every case was deleted. Walk through error to find which ones failed and why.
Processing order is not guaranteed: do not rely on the position within success or error, but on the index field.
The failure reason is the one returned by the business service (case from another company, case not found…) or, by default, Error while deleting case. These labels are not guaranteed to be stable: route your errors on a case being present in error[] rather than on the exact wording.
Request errors
In these cases, no case is deleted:
| Status | Context |
|---|---|
400 | Empty caseIds, more than 50 identifiers, non-numeric identifier, or the same identifier sent several times |
403 | One of the two required permissions is missing |
429 | Rate limit of 10 requests per minute exceeded on this endpoint |
Case Analysis
Endpoint: GET /cases/:caseId/analysis
Description
Returns the full trust analysis of a case: overall score, signals per business dimension (geolocation, device, photo, document…), the analysis result of each photo and, if a document analysis was triggered, the detail per document.
The document analysis (OCR + Itesoft scoring) runs in the background after upload. If it is not finished yet, the documentAnalyses block may be partial — check progressStatusLevel === "ANALYSIS_COMPLETED" before using the document scores.
The Document analysis page describes the full flow: uploading the document (POST /v2/items/:caseId/document), then reading the result with this endpoint. The analysis result webhook pushes the same content as soon as the analysis is finished.
Request
-
URL:
/cases/:caseId/analysis -
HTTP method:
GET -
Path parameters:
caseId:number— Unique identifier of the case.
-
Required headers:
Authorization: Bearer <Your_JWT_Token>
Required Permissions
- Permission API > File > Consult.
- The case must belong to your company.
Example
curl -X GET \
"https://admin.certificall.app/certificall/api/cases/12345/analysis" \
-H "Authorization: Bearer your_jwt_token"
Success response
Status: 200 OK
{
"caseId": 12345,
"trustScore": 86,
"trustLevel": "GOOD",
"itemsAnalyzed": 5,
"signals": [
{ "key": "gps", "score": 95, "trustLevel": "GOOD" },
{ "key": "motion", "score": 80, "trustLevel": "GOOD" },
{ "key": "device", "score": 90, "trustLevel": "GOOD" },
{ "key": "image", "score": 85, "trustLevel": "GOOD" },
{ "key": "duplicate", "score": 100,"trustLevel": "GOOD" },
{ "key": "similar", "score": 100,"trustLevel": "GOOD" },
{ "key": "document", "score": 88, "trustLevel": "GOOD" }
],
"documentAnalyses": [
{
"itemId": 67890,
"expectedDocumentTypes": ["INVOICE"],
"detectedDocumentType": "INVOICE",
"typeMatchScore": 100,
"crossCheckResults": [
{ "fieldCode": "totalAmount", "fieldLabel": "Total amount", "match": "MATCH" },
{ "fieldCode": "customerName", "fieldLabel": "Customer name", "match": "MATCH" }
],
"crossCheckScore": 100,
"suspicionLevel": "NONE",
"evaluation": 96,
"suspicionScore": 96,
"progressStatusLevel": "ANALYSIS_COMPLETED",
"trustScore": 96,
"analysisDetails": [
{
"code": "FONT_CONSISTENCY",
"label": "Font consistency",
"status": "VALID",
"evaluation": 95,
"suspicionLevel": "NONE",
"weight": 2
}
]
}
],
"imageAnalyses": [
{ "itemId": 67891, "trustScore": 92, "trustLevel": "GOOD", "status": "SAFE" },
{ "itemId": 67892, "trustScore": 30, "trustLevel": "SUSPICIOUS", "status": "SUSPECT" }
]
}
Data model
ApiCaseAnalysisDto — case analysis
| Field | Type | Description |
|---|---|---|
caseId | Number | Case identifier. |
trustScore | Number | Overall trust score (0–100, 100 = maximum confidence). |
trustLevel | String | GOOD (70–100) | SUSPICIOUS (30–69) | CRITICAL (0–29). |
itemsAnalyzed | Number | Number of analysed items. |
signals | Array | Score per dimension (see table below). |
documentAnalyses | Array | Detail per analysed document (see below). Empty if the case has no document step. |
imageAnalyses | Array | Analysis result of each photo (see below). Empty if the case contains no photo. |
signals — possible keys
| Key | Analysed dimension |
|---|---|
gps | Geolocation (consistency, accuracy) |
battery | Battery (device state at capture time) |
motion | Motion (stability of the shot) |
device | Device integrity (Play Integrity / attestation) |
image | Photo (detection of a photo of a photo) |
duplicate | Photo already seen: the same photo was already submitted on the platform, in another case or another step. A reuse turns the signal CRITICAL. |
similar | Similar photo: the photo strongly resembles one from another case of your company (the same site presented as several projects, for example). A clue to check, not a proof: the signal goes at most to SUSPICIOUS. |
document | Document analysis (present only if at least one document analysis exists on the case) |
ApiDocumentAnalysisDto — document analysis
| Field | Type | Description |
|---|---|---|
itemId | Number | Item (document) concerned. |
expectedDocumentTypes | String[] | Accepted document types configured on the step. |
detectedDocumentType | String | null | Document type detected by the AI. |
typeMatchScore | Number | null | Type compliance (0–100): 100 if the document matches one of the expected types, 40 otherwise; null if no type was detected or if the step imposes no type ("Other document", "Automatic detection" or "Generic document"). |
crossCheckResults | Array | null | Verdict per cross-checked field: MATCH | MISMATCH | MISSING. The compared values are never returned. |
crossCheckScore | Number | null | Cross consistency (0–100): document ↔ entered data cross-check. |
suspicionScore | Number | null | Anomaly detection (0–100): forensic tampering analysis. |
suspicionLevel | String | null | Suspicion level (NONE, LOW, MEDIUM, HIGH). |
evaluation | Number | null | Tampering analysis score (0–100). |
progressStatusLevel | String | null | ANALYSIS_COMPLETED when the analysis is finished. |
trustScore | Number | null | Document score (0–100): the lowest of the evaluation, typeMatchScore and crossCheckScore scores (a missing score is ignored). The case Trust Score takes the document analysis into account through the document signal. |
analysisDetails | Array | null | Detail of the control criteria: code, label, status, evaluation, suspicionLevel, weight. A criterion can carry a subControls array (same fields, plus message and resultDetails) detailing its sub-controls. |
ApiImageAnalysisDto — photo analysis
One entry per photo still present in the case. A photo analysed several times (after a regeneration, for example) appears only once, with the same analysis as the one used in the case score. A photo for which no analysis was recorded does not appear. A photo analysed without a verdict appears with an empty score, level and verdict.
| Field | Type | Description |
|---|---|---|
itemId | Number | Item (photo) concerned. |
trustScore | Number | null | Photo analysis score (0–100, 100 = maximum confidence): detection of a screen capture or of a photo of another photo. null if the analysis returned no score. |
trustLevel | String | null | GOOD (70–100) | SUSPICIOUS (30–69) | CRITICAL (0–29), computed as for signals. null if trustScore is null. |
status | String | null | Analysis verdict: SAFE | SUSPECT. null as long as the analysis has not returned a verdict. |
Error responses
| Status | Description |
|---|---|
403 Forbidden | The case does not belong to your company, or the analysis option is not active for your company. |
404 Not Found | Case not found. |
Security and Best Practices
- Ensure that all necessary data has been collected before closing a case.
- Only the fields provided in the update request will be modified. Other fields will retain their current values.
- Consider backing up important data before deletion.
- Always verify that the
caseIdcorresponds to the case you want to manipulate. - Metadata must be key-value pairs with string-type values.
- Interactions with the Certificall API must always be performed via a secure connection (HTTPS).
- Store and manage the authentication token securely.
By following these instructions, you will be able to securely manage your cases via the Certificall API.