Skip to main content

Flows & Groups

Before you can call the IDV API or generate a Web SDK Link, you need a flow. Flows are created and managed in the merchant portal and define exactly how a verification behaves — which fields and documents are required, which biometric method is used, and what happens after a verification completes.

Flows​

A flow is a named, reusable verification configuration. Every call to POST /v2/idv/verify (or every Web SDK Link) runs against a specific flow, identified by its flowId.

Creating a flow​

  1. Log in to the merchant portal and open the Configuration page.
  2. Create a new flow and give it a name (e.g. "Standard Onboarding" or "High-Risk Region KYC").
  3. Configure the flow's settings (below).
  4. Save the flow. The portal generates a flowId — copy it from the flow list; you'll pass this as the flowId parameter on every verification request.

What a flow configures​

SettingDescription
Required fieldsWhich optional fields on /v2/idv/verify (e.g. dob, phone, email, address fields, ssn) must be present.
Document typesWhich of PASSPORT, DRIVERS, ID_CARD are accepted, and whether front/back sides are required per type.
Biometric methodWhether the flow expects a static selfie upload, a live selfie capture, or a liveness check.
Document upload methodWhether documents are submitted as a file upload or captured live (DocumentUploadType: fileUpload or fileCapture).
Age rulesMinimum and maximum age (1–120) — verifications for users outside this range are rejected.
Geo-blockingCountries blocked for this flow specifically, in addition to any account-wide blocked countries.
Country overridesPer-country customization — a different set of required fields/document types for a specific country, or marking a country fully restricted for this flow (see Restricted Jurisdictions).
Document types are still limited

Only PASSPORT, DRIVERS, and ID_CARD are currently supported in the portal, even though additional document type options may appear reserved for future use.

Groups​

A group is a named collection of one or more existing flows, created on the portal's Groups page. Groups are useful for organizing flows (e.g. by product line or region), and are required if you want to generate a Web SDK Link.

Creating a group​

  1. Open the Groups page in the portal.
  2. Create a new group, give it a name and optional description, and select one or more existing flows to include.
  3. Save the group. The portal generates a groupId.

Using a group​

groupingId is an optional parameter on POST /v2/idv/verify. If you provide it, the flow referenced by flowId must be a member of that group, or the request is rejected with a 400 error. If omitted, the verification isn't associated with any group.

Generating a Web SDK Link, however, always requires both a flowId and a groupId that contains it — see Web SDK Link.

Duplicate detection scope​

groupingId also determines how narrowly a duplicate identity (the same person's face) is detected:

  • With a groupingId — the duplicate-face check is scoped to that group. A person already verified under that group is rejected as a duplicate, but the same person can be verified again under a different group (or with no group at all) without being flagged.
  • Without a groupingId — the duplicate-face check applies across your entire merchant account. The same person cannot complete verification more than once, regardless of grouping.

externalUserId uniqueness is unaffected by grouping — a given externalUserId can only be registered once per merchant account, whether or not a groupingId is supplied.

Next Steps​

  • IDV API Reference — call /v2/idv/verify directly using a flowId
  • Web SDK Link — generate a hosted verification link for a flow instead of integrating the API