Migrate Bank Account Document Check to Document Trust

Bank account details documents can now be analyzed with Document Trust, using the bank_account type. Your current integration of /verifications/bank_accounts keeps working: migrate when it suits you.

Why migrate

  • Tolerant name matching: you no longer need to send the holder name exactly as printed. Case, accents and punctuation are handled, and close matches are reported as close. For a company, the legal form (SAS, GmbH…) printed on the document is ignored only when you send none: if you send Dupont SAS, DUPONT is close and DUPONT SCI is no_match.
  • More countries: the 111 countries that use an IBAN (see the list).
  • BIC read on documents from every country, not only French ones. Sending a BIC is now optional everywhere.
  • Detailed checks: for each of iban, bic and account_holder, you get the value read on the document, the value you sent, and a match_level.
  • Optional fraud detection with analysis_type[fraud_level] (standard or advanced), and a risk label.
  • Larger files: up to 25 MB.

Before you start

Document Trust requires a change of your contract and add-on. Contact your account manager to switch.

Endpoints and webhook

Bank Account Document CheckDocument Trust
CreatePOST /verifications/bank_accountsPOST /document_analyses with type=bank_account
RetrieveGET /verifications/bank_accounts/{id}GET /document_analyses/{id}
ListGET /verifications/bank_accountsGET /document_analyses?type[eq]=bank_account
Webhookverification.bank_account.donedocument_analysis.done

Verifications you created with /verifications/bank_accounts stay available on the same endpoints.

Request

Bank Account Document CheckDocument Trust
—type=bank_account (required)
file (PDF, PNG, JPG, JPEG — 10 MB)file (PDF, PNG, JPG, JPEG — 25 MB, 10 pages max; PDF only with fraud_level=standard)
ibanchecks[iban]
bicchecks[bic]
natural_person[first_name]checks[account_holder][type]=natural_person and checks[account_holder][first_name]
natural_person[last_name]checks[account_holder][last_name]
legal_person[name]checks[account_holder][type]=legal_person and checks[account_holder][company_name]
workspace_id, workflow_session_id, previous_attempt_idUnchanged
—analysis_type[fraud_level] (optional): standard or advanced

With checks[account_holder][type]=natural_person, both checks[account_holder][first_name] and checks[account_holder][last_name] are required. Bank Account Document Check accepted one of the two only.

# Before
curl --location --request POST '{baseUrl}/verifications/bank_accounts' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/path/to/bank_details.pdf"' \
--form 'iban="FR7630006000011234567890189"' \
--form 'natural_person[first_name]="John"' \
--form 'natural_person[last_name]="Doe"'

# After
curl --location --request POST '{baseUrl}/document_analyses' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/path/to/bank_details.pdf"' \
--form 'type="bank_account"' \
--form 'checks[iban]="FR7630006000011234567890189"' \
--form 'checks[account_holder][type]="natural_person"' \
--form 'checks[account_holder][first_name]="John"' \
--form 'checks[account_holder][last_name]="Doe"'

With an Applicant

curl --location --request POST '{baseUrl}/document_analyses' \
--header 'Authorization: Bearer {apiKey}' \
--header 'Content-Type: application/json' \
--data '{"applicant_id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c", "type": "bank_account"}'

No checks in this variant: they are taken from the Applicant. The IBAN and BIC come from its bank account, and account_holder from its identity (natural person) or its company name (legal person).

The Document Analysis is created with the status awaiting_data, and keeps it until the Applicant sends the file through the Workflow Session Link. Bank Account Document Check behaves the same way.

Response

Bank Account Document CheckDocument Trust
status: pending, awaiting_data, verified, failed, inconclusivestatus: pending, awaiting_data, done, failed, inconclusive
data.extracted_from_document.ibanextracted_from_document.iban
data.extracted_from_document.bicextracted_from_document.bic
—checks.iban, checks.bic, checks.account_holder: extracted, expected, match_level (exact, close, no_match)
—document_classification: document type and country detected
—fraud_risk_analysis: risk label and indicators, when fraud_level is set
{
  "status": "done",
  "status_codes": [],
  "type": "bank_account",
  "extracted_from_document": {
    "iban": "FR7630006000011234567890189",
    "bic": "AGRIFRPPXXX"
  },
  "checks": {
    "iban": { "extracted": "FR7630006000011234567890189", "expected": "FR7630006000011234567890189", "match_level": "exact" },
    "account_holder": { "extracted": "Jean Dupont", "expected": "Jean Dupont", "match_level": "exact" }
  }
}

Status codes

Bank Account Document CheckDocument TrustMeaning
BAV_1100DA_1100Technical issue, retry later
BAV_1408, BAV_1501DA_1003, DA_1004The document is not bank account details
BAV_1502, BAV_1503fraud_risk_analysis, DA_3001Tampering — only reported when fraud_level is set
BAV_1601DA_2004, DA_2501IBAN does not match the one you sent, or no IBAN on the document
BAV_1602DA_2601The IBAN read is not valid
BAV_1604DA_2005, DA_2502, DA_2602BIC does not match the one you sent, not found, or not valid
BAV_1611, BAV_1612, BAV_1613DA_2001The holder does not match the natural person you sent
BAV_1614DA_2006The holder does not match the company you sent
—DA_3004Fraud detection unavailable — only when fraud_level is set. Status inconclusive, retry later
—DA_3003Quality control unavailable — only with fraud_level=advanced. Status inconclusive, retry later
BAV_1603No equivalentIBAN found on a public website: not checked
BAV_1103, BAV_1104, BAV_1105, BAV_1106, BAV_1107, BAV_1200 to BAV_1208, BAV_1508No equivalentFile and image quality issues have no dedicated code

When no BIC is printed on the document, Document Trust only fails if you sent checks[bic] (DA_2502). When a BIC is printed but is not valid or does not match the country of the IBAN, it always fails (DA_2602), even if you sent no BIC.

Test in Sandbox

Use the filenames listed in Testing Document Trust Analysis in Sandbox, with type=bank_account.

The simulated document always holds the holder Jean Dupont (a natural person), the IBAN FR7630006000011234567890189 and the BIC AGRIFRPPXXX. Send these values in checks to get done with done.pdf: any other value does not match, and the analysis fails.