Overview

Dotfile verifies the companies and people a business onboards. A case is one customer under
verification: the companies and individuals it involves, the checks performed on them, and the
decision that closes it. The API covers that lifecycle end to end — creation, check execution,
results, review — and the console acts on the same data, so the two can be mixed on the same case.

Connection details

API keys are workspace-wide and generated by an admin in the workspace settings. See
Authentication.

Your first call

A single POST creates the case, the entities it verifies and the checks that verify them.
name is the only required field; template_key determines which checks are created.

curl -X POST https://api.dotfile.com/v1/cases \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp onboarding",
    "template_key": "kyb_standard",
    "companies": [
      {
        "type": "main",
        "name": "Acme Corp",
        "country": "FR",
        "registration_number": "552100554"
      }
    ]
  }'

The response contains the complete case: its id, and every company and individual with the id
assigned to it. Checks then run asynchronously, and Webhooks report their
outcome.

The five objects

A case also carries an external_id of your choosing. Retrieval accepts it in place of the
Dotfile id, so a case can be addressed by the identifier your own system already stores.

Relations

Companies and individuals are connected by relations, not by nesting. A relation carries a role —
shareholder or legal_representative — an ownership percentage and a position. Attributes of
the person rather than of the link, such as is_beneficial_owner, sit on the individual.

A KYB case has one company of type main, any number of affiliated companies, and the
individuals holding or representing them. Finding company data populates
those entities from official registries rather than from user input.

Checks and templates

Nine check types exist: document, id_document, id_verification, ekyc, aml,
company_monitoring, electronic_signature, fraud_database and online_reputation. Checks run
asynchronously, and a check whose provider cannot decide alone reaches a state requiring a verdict,
reported as Check.ReviewNeeded. That verdict is recorded in the console or over the API.

Checks are not normally created one by one. A template targets the main company, affiliated
companies and individuals independently, so passing a template_key at case creation produces the
correct set of checks for every entity in the case.

The API specifications section follows the same structure: one group per object, and inside it
a page per endpoint.

Next