Verifying a Document

A document check collects one document of a given type on one entity of a case — a company or
an individual — and holds the files, the automated analysis and the decision taken on them.

The shared envelope, the status model and the general review mechanism are described in
The Check object. This page covers what is specific to the document type.

The check object

On the envelope, subtype is document_type:{document_type_key} and document_type_key is
exposed directly, so a webhook payload identifies the document without a second request.

Creating a check

POST /v1/checks/document requires a company_id or an individual_id, and
settings.document_type_key. Files are optional.

curl -X POST https://api.dotfile.com/v1/checks/document \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "de0d49bd-ea3d-4943-8bf6-dc0034aa6ec4",
    "settings": {"document_type_key": "registration_certificate"}
  }'

Created without data.files, the check is in_progress and waits for files from a subsequent
request, from the client portal, or from the console. Created with files, processing starts
immediately.

Document types

Each workspace is provisioned with a set of document types and can define additional ones. Both
are addressed through document_type_key, and each type declares the entity types it applies to.

The table above lists the provisioned defaults. A workspace can rename, archive or add types, so
List all document types is the authoritative list for a given
workspace.

curl -G https://api.dotfile.com/v1/document_types \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -d limit=100

Archived types are excluded by default; pass include_archived=true to include them. Two errors
are specific to this field:

Document types are created in the console, described in
Custom document types.

Files

Files are supplied as upload_ref values obtained from Upload a file. A
check accepts a maximum of 10 files, returned as data.document_file_ids.

curl -X POST https://api.dotfile.com/v1/checks/document \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "individual_id": "4b36ce30-3d90-421a-b2d9-a046e5e4cfef",
    "settings": {"document_type_key": "proof_of_address"},
    "data": {"files": [{"upload_ref": "'$UPLOAD_REF'"}]}
  }'

Add files attaches files to an existing check. It is accepted only while
the check is in_progress, rejected or expired, which covers initial collection and
recollection after a rejection. Any other status returns 400. Upload mechanics and limits are
described in The File object.

Automated analysis

settings.document_analysis submits the document to an analysis model before manual review.

parameters is discriminated by model:

{
  "company_id": "de0d49bd-ea3d-4943-8bf6-dc0034aa6ec4",
  "settings": {
    "document_type_key": "registration_certificate",
    "document_analysis": {
      "automatic_approval": true,
      "automatic_rejection": false,
      "parameters": {
        "model": "registration_certificate",
        "max_age_in_days": 92,
        "authorized_documents": ["kbis"]
      }
    }
  },
  "data": {"files": [{"upload_ref": "..."}]}
}

Results are returned on two fields. data.detailed_results.document_analysis contains one
{result, expected, received} object per control point: valid_document_type,
valid_age_in_days, name_matching, address_matching, and registration_number_matching for
the registration_certificate model. data.information.document_analysis contains the extracted
values: issuing_date, address, name, document_type. The prompt model returns a result
without a structured breakdown.

detailed_results is marked deprecated in the schema. It remains the only structured breakdown
exposed by the API; the analysis-result model that replaces it is not yet public.

Model configuration per document type is described in
Default document AI analysis and
Custom document AI analysis.

Fraud analysis

settings.fraud_analysis submits the document to a forensic analysis for signs of tampering. It
accepts a single field, enabled, and is available on
Create a Document check and Add files. It is
billed on usage.

Two constraints apply. The setting is not returned in the check response. And when the forensic
analysis flags a document, the check is set to need_review and adding files does not re-run it,
so that the outcome of the analysis is not exposed through repeated submissions. See
Document forensics.

Status

The status reached after files are received depends on the analysis configured.

Transitions taken without a request record review.reviewer_type as system; a decision sent
over the API records api.

Forcing a review

POST /v1/checks/document/{id}/force_review moves a check from in_progress to need_review
without submitting further files.

curl -X POST https://api.dotfile.com/v1/checks/document/$CHECK_ID/force_review \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY"

It returns 400 if the check holds no file, or if its status is neither in_progress nor
need_review. document is the only check type exposing this endpoint.

Reviewing the check

curl -X PATCH https://api.dotfile.com/v1/checks/document/$CHECK_ID/review \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "comment": "Certificate matches the registry extract"}'

action is approve or reject, comment is optional, and override set to true changes a
decision already recorded. review.reviewer_type is set to api.

Endpoints

• Create a Document check
• Retrieve a Document check
• Add files
• Force review
• Review a Document check
• List all document types
• Document check for the product documentation