Verifying company - API only (v1)

Preview / Alpha

This step is in preview / alpha. The functionality and subsequently the documentation can still change. This step is being rolled out gradually and is not yet selectable in the flow editor.

Automated verification of a French company against the official register

Verifies a French company against the official register (societe.com via the IDnow company analysis service) using only a company identifier supplied through the API — no document images and no user interaction. The step is API-only: it runs as part of a session triggered by your backend, and routes the flow based on whether the company is found and, optionally, whether the requester or the submitted name matches the official register record.

The submitted companyReference data block identifies the company: a SIREN (9 digits) or SIRET (14 digits) and the registration country. When you enable identity or name cross-checks, the flow verifies that the requester is a legal representative of the company, or that the submitted company name matches the registered name.

Both the identifier format (length and Luhn checksum over the full submitted value) and the registration country are validated when the session is created — invalid identifiers never reach the register lookup and consume no verification credits.

---

Key features

• API-only verification: no document capture, no end-user interaction — the whole check is driven by the session input.
• Official register data: returns the registered name, legal form, address, activity, share capital, and legal representatives as a company data block.
• Optional cross-checks: compare the requester's identity against the company's legal representatives, or the submitted name against the registered name.
• Unified Verification output: results arrive in the standard Verification data block with an electronicRecordCheck method, checks, and a downloadable analysis report as evidence.

---

Configuration

Option	Type	Required	Default	Description
config	object	Yes	—	Environment-specific configuration.
config.live.realm	string	Yes	—	The IDCheck.io realm for the company analysis service in this environment. Provided by IDnow during onboarding. (live)
config.staging.realm	string	Yes	—	The IDCheck.io realm for the company analysis service in this environment. Provided by IDnow during onboarding. (staging)
compareIdentity	boolean	No	false	When true, cross-checks the requester BasicIdentity against the company legal representatives.
compareLegalName	boolean	No	false	When true, cross-checks the submitted company name against the official register record. The comparison runs only when the name-match check is enabled for your realm — contact IDnow during onboarding to confirm.

The realm for each environment is provided by IDnow during onboarding.

This step requires the register-check capability to be enabled for your realm — contact IDnow during onboarding to confirm.

---

Input data blocks

Data block	Required	Description
CompanyReference	Yes	Company register reference: the registration country and the company identifier (SIREN or SIRET for France). The registered name is optional.
BasicIdentity	Conditional	Identity of the person requesting verification, cross-checked against the company legal representatives. Present only when compareIdentity is true.

The companyReference.legalPersonId accepts a SIREN (9 digits) or a SIRET (14 digits). A SIRET is reduced to its SIREN before the register lookup; the input you submitted is preserved as-is in the session's input data. registrationCountry currently accepts FR only.

---

Routes

Route	Description
match_found	The company was found in the official register and every enabled cross-check matched.
no_match_found	The company was not found in the official register. No company data block is produced.
partial_match	Available only when compareIdentity is true or only when compareLegalName is true. The company was found in the official register, but an enabled identity or name cross-check did not match.

The partial_match route is available only when compareIdentity or compareLegalName is enabled. A flow that wires a transition to partial_match without either option enabled fails validation.

---

Output data blocks

Route	Data blocks produced
match_found	Company, Verification
no_match_found	Verification
partial_match	Company, Verification Available only when compareIdentity is true or only when compareLegalName is true.

On no_match_found, no company data block is produced — the register returns no usable company data for an unknown identifier. The analysis report evidence is attached on every route.

---

Example payloads

Create a session with a companyReference input block:

curl --request POST https://localhost:3000/api/v1/flows/{flowId}/live/sessions \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--header "User-Agent: my-backend-service/1.0" \
--data '{
  "input": {
    "companyReference": {
      "registrationCountry": "FR",
      "legalPersonId": "52076922500043",
      "legalPersonName": "IDNOW SAS"
    }
  },
  "metadata": {
    "subjectId": "customer-internal-subject-id-123"
  }
}'

The session results contain the company data block with the official register record (see Data blocks) and a verification data block with an electronicRecordCheck method (see Data blocks).