Skip to main content

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).

Option required

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​

#StepEndpoint
1AuthenticatePOST /auth/token — see Public Authentication
2Retrieve the frame and the stepId of the document stepGET /frames — see Certificate Creation
3Create a casePOST /cases/create — see Case Management
4Upload the documentPOST /v2/items/:caseId/document
5Close the caseGET /cases/close/:caseId — see Case Management
6Retrieve the analysis resultGET /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.

info

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.

Deprecated former URL

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​

ConstraintValue
Accepted formatsPDF, JPEG, PNG
Maximum size~10 MB
Type checkThe 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 createItemDto JSON — 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.

Asynchronous 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​

FieldTypeDescription
caseIdNumberCase identifier.
trustScoreNumberOverall trust score of the case (0-100).
trustLevelStringGOOD | SUSPICIOUS | CRITICAL.
signalsArrayScore per dimension: gps, battery, motion, device, image, duplicate, similar, document. The document signal only appears if a document analysis exists on the case.
itemsAnalyzedNumberNumber of analyzed items.
documentAnalysesArrayDetails of each document analysis (see below).

ApiDocumentAnalysisDto — analysis of a document​

FieldTypeDescription
itemIdNumberItem (document) concerned.
expectedDocumentTypesString[]Accepted document types configured on the step.
detectedDocumentTypeString | nullDetected document type.
typeMatchScoreNumber | nullType 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").
crossCheckResultsArray | nullVerdict per cross-checked field: MATCH | MISMATCH | MISSING. Compared values are never returned (zero personal data).
crossCheckScoreNumber | nullCross-check consistency (0-100): document ↔ entered data cross-check.
suspicionScoreNumber | nullAnomaly analysis (0-100): forensic falsification detection.
suspicionLevelString | nullSuspicion level (NONE, LOW, MEDIUM, HIGH…).
evaluationNumber | nullFalsification analysis score (0-100).
progressStatusLevelString | nullAnalysis progress (ANALYSIS_COMPLETED = done).
trustScoreNumber | nullDocument 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.
analysisDetailsArray | nullDetails 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​

ScoreAPI field
Falsification analysisevaluation
Document type compliancetypeMatchScore
Cross-check consistencycrossCheckScore
Overall document scoretrustScore: 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.
Avoid polling

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​

  1. Automatic document checking: your back-office uploads the received supporting documents, waits for ANALYSIS_COMPLETED, and routes the case (automatic validation if trustLevel = GOOD, manual review otherwise).
  2. Digital vault: every uploaded document is certified (eIDAS timestamp, signature) — you retrieve the certificates through the reports.
  3. Minimized collection (GDPR): with deletion after analysis, your information system neither stores nor receives any document — only the scores from this API.