Finding Company data

The company data endpoints query business registries and commercial data providers to locate a
company, return its official profile and ownership structure, and order the underlying registry
documents. They allow a case to be prefilled from an official source rather than from data typed
by the end user.

The flow has three stages: search returns the companies matching a query, fetch resolves
one of them into a full profile, and document orders purchase documents from the registry.

Country coverage

Coverage depends on the company data vendors configured in the workspace, so it is a property of
the workspace rather than of the API. List countries returns the
current coverage and is the correct source for any country selector shown to an end user.

curl -G https://api.dotfile.com/v1/company-data/countries \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY"

Each entry carries a code, a name and the vendor covering it. Three parameters filter the
list:

Searching for a company

Search companies takes a country and one search key.

curl -G https://api.dotfile.com/v1/company-data/search \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -d country=FR -d name="Dotfile"

A name search returns a candidate set, not a single company. Company names are not unique within
a registry: two active companies can share a name in the same country and the same register, and
a search is additionally executed against every vendor configured for that country before results
are deduplicated on registration number. No downstream call can determine which candidate the end
customer meant.

Two resolutions are valid:

• Selection by the end user. Render the candidates — name, registration number, address,
  status — and have the user identify the company.
• Lookup by a trusted registration number. When a registration number is already held, search
  on registration_number rather than on name.

Selecting the first result is not a resolution: it onboards an entity the customer did not name,
and every check created afterwards then verifies the wrong company.

Each result carries:

Fetching company data

curl https://api.dotfile.com/v1/company-data/fetch/$SEARCH_REF \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY"

The response holds the company as the source reports it: name, commercial_name,
registration_number, country, status, registration_date, legal_form,
entity_legal_form and its label, address, share_capital, tax_identification_number,
website_url and classifications.

It also holds the entities attached to the company, in five lists:

In the three raw lists, entity_type discriminates an individual from a company. Both merged
lists expose only the entity's relation to the main company.

A fetch counts against the workspace allowance over a rolling 30-day window. Beyond it, the call
returns 400 with the code WORKSPACE_LIMIT_REACHED. Search is not capped.

Individual consolidation

Registries commonly report the same person up to three times — as a beneficial owner, as a
shareholder and as a legal representative — each occurrence carrying a different subset of the
data. merged_individuals resolves those occurrences into one entry per person: roles
accumulates, is_beneficial_owner is taken from the beneficial-owner occurrence, and where two
occurrences disagree on a field the higher-priority role wins, in the order beneficial owner,
shareholder, legal representative.

Individuals should be created from merged_individuals. The raw lists remain available when the
provenance of a value matters.

Two occurrences are consolidated when both conditions hold:

• The names match. Both occurrences must carry a first and a last name; a person reported as
  a single unparsed string is never consolidated. Names are compared lowercased and stripped of
  diacritics, whitespace and hyphens, and must reach a Sørensen-Dice similarity above 0.9. A
  source splitting given names differently — Mehmet Oguz against Mehmet with middle name
  Oguz — still matches, provided the surname is identical and the given names form an
  order-preserving prefix.
• The birth dates do not contradict. Only the components present on both sides are compared,
  so a year-only date matches a full one. Where one side carries no birth date, the name decides.

Companies reported as shareholders or beneficial owners are excluded from merged_individuals
and appear in merged_companies.

Company documents

The documents that can be ordered for a company — registry extract, articles of association,
annual accounts and others — depend on the country and on the providers covering it.
List available documents is the authoritative list. It
requires either a company_id, or a country together with a registration_number.

curl -G https://api.dotfile.com/v1/company-data/available-documents \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -d country=FR -d registration_number=552100554

product_ref encodes a vendor and that vendor's product code. Both change over time, so a value
copied into application code eventually stops resolving; it must be read from this endpoint.

Create a document order accepts it:

curl -X POST https://api.dotfile.com/v1/company-data/document-orders \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "a7402197-0314-4c8f-8146-15ec0fa02193", "product_ref": "'$PRODUCT_REF'"}'

The company must already hold a country and a registration number. Ordering is idempotent: an
existing order for the same company and the same product is returned unchanged rather than
purchased again, unless that order failed, in which case the purchase is retried.

file_id is null until the order completes, then identifies a file retrievable with
Download a file. Orders are also returned on the company itself, under
document_orders — see Retrieve a company. The events
DocumentOrder.Completed and DocumentOrder.Failed report completion without polling; see
Webhooks.

Entity legal forms

List entity legal forms returns the supported
ISO 20275
codes, filterable by country and subdivision. A country of null denotes a form available
in every country. These are the values accepted by entity_legal_form on
Create a company, and returned in the same field by a fetch.

Related

• Start KYB process — the complete flow, from search to decision
• Create a company and Create an individual —
  creating case entities from fetched data
• The File Object — storage and retrieval of ordered documents