Identity verification and AML

There are two calls. Use the one that matches the check you want.

You need	Call
An identity verification the person completes, with or without AML	`POST /api/v1/id-verifications/send`
AML only, on a client already in the practice, with no invite email	`POST /api/v1/id-verifications/aml-checks`

Both need canWrite: true. Billing is checked before the check is created. If the wallet cannot cover the fee, you get 400 and nothing is charged and nothing is created.

Verify someone

POST /api/v1/id-verifications/send emails a link unless mute is true. Existing client. Pass entityKey. Override entityEmail or entityMobile for this invite only. Not on file. Omit entityKey. Send entityName, entityEmail, and optionally entityMobile.

{
  "entityKey": "2c4f6a88-1b3d-5e7f-90ab-cdef12345678",
  "includeAml": "Basic",
  "mute": false
}

includeAml:

Value	What runs
omitted	Identity verification only
`Basic`	Identity verification plus basic AML
`Extensive`	Identity verification plus extensive AML

The response tells you what was reserved and where to send the person:

verificationKey is the id of this request. Store it.
accessUrl is the client-facing verification link.
emailSent is whether the invitation email went out.
wallet.identityVerificationFromWallet is the identity fee taken from the practice wallet.
wallet.amlOnWalletBecausePoolEmpty is the AML amount charged to the wallet because the AML subscription pool did not cover it.
wallet.totalWalletRequired is the total reserved from the wallet for this send.

mute: true skips the email. accessUrl is still the direct client link, the same URL the email would have contained. Deliver it yourself. This is different from an eForm whose send step failed: a muted verification is a real check, not a draft.

Standalone AML

POST /api/v1/id-verifications/aml-checks does not invite anyone and does not collect an identity document. The client must already exist.

{
  "entityKey": "2c4f6a88-1b3d-5e7f-90ab-cdef12345678",
  "checkType": "extensive",
  "enableMonitoring": false
}

`checkType`	Screening
`standard`	Sanctions and PEP level 1
`extensive`	Enhanced due diligence, PEP level 4, adverse media, exclusion lists

enableMonitoring defaults to false. Set it true only when the practice wants continuous monitoring on that check. Billing uses the practice AML subscription pool first, then the wallet for anything the pool does not cover. That calculation happens before the check exists. If the wallet is short and auto-topup is on, OnboardMe attempts the top-up first. If it still cannot pay, you get 400 and no check.

Certificate

When an identity verification has a certificate, download it with:

GET /api/v1/id-verifications/entities/{entityKey}/certificate

The response is the PDF. A 404 means there is no certificate yet for that client, or the entity is not in this practice. Do not poll this in a tight loop. Trigger the check, then download when your own workflow says the check is complete.

Failures worth handling

Status	Meaning
400	Wallet or subscription cannot cover the fee, or the body is missing a recipient. No charge on the wallet-short case.
403	Read-only credential.
404	`entityKey` is not in this practice.
429	Rate limit. Honour `Retry-After`.

Identity checks on a proposal or an onboarding are configured on those create calls (verificationMethod of Basic, Standard, Enhanced, Comprehensive, or the Annature methods). You do not also call id-verifications/send for the same person unless you want a second, separate check. See Proposals and Onboarding jobs.

ID verification reference

Send, standalone AML, and the certificate download.

Core Concepts

Guides

Identity verification and AML

Verify someone

Standalone AML

Certificate

Failures worth handling

ID verification reference

​Verify someone

​Standalone AML

​Certificate

​Failures worth handling

ID verification reference

Verify someone

Standalone AML

Certificate

Failures worth handling