API — Document analysis
This page describes how to use document analysis through the Certificall API: sending a document to analyze, then retrieving the result (scores, verdicts and trust level).
Document analysis is an option of your contract, enabled by your Certificall contact. Frame configuration (accepted document types, cross-check, GDPR deletion) is described in Document analysis — administration.
Flow overview
| # | Step | Endpoint |
|---|---|---|
| 1 | Authenticate | POST /auth/token — see Public Authentication |
| 2 | Retrieve the frame and the stepId of the document step | GET /frames — see Certificate Creation |
| 3 | Create a case | POST /cases/create — see Case Management |
| 4 | Upload the document | POST /v2/items/:caseId/document |
| 5 | Close the case | GET /cases/close/:caseId — see Case Management |
| 6 | Retrieve the analysis result | GET /cases/:caseId/analysis, or the analysis result webhook |
Every request (except authentication) requires the header:
Authorization: Bearer <Your_JWT_Token>
1. Upload the document to analyze
Endpoint: POST /v2/items/:caseId/document
Description
Creates an item on a Document upload step and triggers document analysis if the step is configured for it. The analysis runs asynchronously: its result is not in this endpoint's response.
This endpoint only accepts Document upload steps (403 otherwise) and requires the API > File > Create permission — the same as for case creation, no extra permission is needed.
If your API key holds the API > Item > Create media permission, the general endpoint POST /v2/items/:caseId (photo, video, signature, document) also accepts documents — see Item Management.
POST /certificall/api/items/:caseId/document, without the /v2 prefix, still works but is deprecated. See Migrating from v1.
Request
- URL:
/v2/certificall/api/items/:caseId/document - HTTP Method:
POST - Required headers:
Authorization: Bearer <Your_JWT_Token>
Content-Type: multipart/form-data - Body (multipart form-data):
file: the document to analyze;createItemDto: stringified JSON object (stepId,data,clientAppName,clientAppVersion,frontCreatedAt, device information…) — full field details in Item Management.
File constraints
| Constraint | Value |
|---|---|
| Accepted formats | PDF, JPEG, PNG |
| Maximum size | ~10 MB |
| Type check | The file's actual type is checked (binary signature), not just its extension. |
Request example
curl -X POST "https://admin.certificall.app/v2/certificall/api/items/12345/document" \
-H "Authorization: Bearer your_jwt_token" \
-F "file=@/path/to/document.pdf" \
-F 'createItemDto={
"companyId": 1,
"stepId": 101,
"data": "document.pdf",
"clientAppName": "My Back-Office",
"clientAppVersion": "2.4.0",
"frontCreatedAt": "2026-08-21T14:29:41+02:00",
"userDeviceManufacturer": "Server",
"userDeviceModel": "API",
"userDeviceName": "integration-api",
"userDevicePlatform": "Server",
"userDeviceOs": "Linux",
"userDeviceOsVersion": "1.0"
}'
Responses
- 200 OK: item created. For a configured step, document analysis starts asynchronously.
- 400 Bad Request: v2 contract field missing, file too large, unsupported file type or malformed
createItemDtoJSON — the message states the cause. - 403 Forbidden: the targeted step is not a Document upload step, or the case does not belong to your company.
- 404 Not Found: no step found for this
stepId.
2. Retrieve the analysis result
Endpoint: GET /cases/:caseId/analysis
Description
Returns the full trust analysis of the case: the overall trust score (Trust Score), the signals per dimension (geolocation, device, photo, document…), and the details of each document analysis.
Document analysis usually takes a few dozen seconds after the upload. Until it is complete, the documentAnalyses block may be partial — rely on the progressStatusLevel field (ANALYSIS_COMPLETED = done) before using the scores.
Request
- URL:
/cases/:caseId/analysis - HTTP Method:
GET - Path parameters:
caseId:number— the case identifier.
- Required headers:
Authorization: Bearer <Your_JWT_Token>
Successful response
- Status Code: 200 OK
- Type:
ApiCaseAnalysisDto
{
"caseId": 798,
"trustScore": 86,
"trustLevel": "GOOD",
"itemsAnalyzed": 5,
"signals": [
{ "key": "gps", "score": 95, "trustLevel": "GOOD" },
{ "key": "device", "score": 90, "trustLevel": "GOOD" },
{ "key": "document", "score": 88, "trustLevel": "GOOD" }
],
"documentAnalyses": [
{
"itemId": 12345,
"expectedDocumentTypes": ["INVOICE"],
"detectedDocumentType": "INVOICE",
"typeMatchScore": 100,
"crossCheckResults": [
{ "fieldCode": "totalAmount", "fieldLabel": "Montant total", "match": "MATCH" },
{ "fieldCode": "customerName", "fieldLabel": "Nom du client", "match": "MATCH" }
],
"crossCheckScore": 100,
"suspicionLevel": "NONE",
"evaluation": 96,
"suspicionScore": 96,
"progressStatusLevel": "ANALYSIS_COMPLETED",
"trustScore": 96,
"analysisDetails": [
{
"code": "FONT_CONSISTENCY",
"label": "Cohérence des polices",
"status": "VALID",
"evaluation": 95,
"suspicionLevel": "NONE",
"weight": 2
}
]
}
]
}
Data model
ApiCaseAnalysisDto — case analysis
| Field | Type | Description |
|---|---|---|
caseId | Number | Case identifier. |
trustScore | Number | Overall trust score of the case (0-100). |
trustLevel | String | GOOD | SUSPICIOUS | CRITICAL. |
signals | Array | Score per dimension: gps, battery, motion, device, image, duplicate, similar, document. The document signal only appears if a document analysis exists on the case. |
itemsAnalyzed | Number | Number of analyzed items. |
documentAnalyses | Array | Details of each document analysis (see below). |
ApiDocumentAnalysisDto — analysis of a document
| Field | Type | Description |
|---|---|---|
itemId | Number | Item (document) concerned. |
expectedDocumentTypes | String[] | Accepted document types configured on the step. |
detectedDocumentType | String | null | Detected document type. |
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. Compared values are never returned (zero personal data). |
crossCheckScore | Number | null | Cross-check consistency (0-100): document ↔ entered data cross-check. |
suspicionScore | Number | null | Anomaly analysis (0-100): forensic falsification detection. |
suspicionLevel | String | null | Suspicion level (NONE, LOW, MEDIUM, HIGH…). |
evaluation | Number | null | Falsification analysis score (0-100). |
progressStatusLevel | String | null | Analysis progress (ANALYSIS_COMPLETED = done). |
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 document analysis into account through the document signal. |
analysisDetails | Array | null | Details of the control criteria: code, label, status, evaluation (0-100), suspicionLevel, weight. A criterion may carry a subControls array (same fields, plus message and resultDetails) detailing its sub-controls. |
Mapping with the triple scoring
| Score | API field |
|---|---|
| Falsification analysis | evaluation |
| Document type compliance | typeMatchScore |
| Cross-check consistency | crossCheckScore |
| Overall document score | trustScore: the lowest of the three scores above |
Error responses
- 403 Forbidden: the case does not belong to your company, or the analysis option is not active for your company (global switch, turns off every analysis).
- 404 Not Found: case not found.
Rather than calling this endpoint in a loop, get notified: the analysis result webhook sends you exactly this content as soon as the analysis is complete.
Privacy: zero personal data
The analysis API never returns values extracted from the document (names, amounts, dates…). Only facts are exposed: verdicts (MATCH/MISMATCH/MISSING), scores and control criteria. Combined with the "Delete the document after analysis" option, this approach allows an integration fully compatible with your GDPR policy: you only keep the result.
Use cases
- Automatic document checking: your back-office uploads the received supporting documents, waits for
ANALYSIS_COMPLETED, and routes the case (automatic validation iftrustLevel = GOOD, manual review otherwise). - Digital vault: every uploaded document is certified (eIDAS timestamp, signature) — you retrieve the certificates through the reports.
- Minimized collection (GDPR): with deletion after analysis, your information system neither stores nor receives any document — only the scores from this API.