Skip to main content
A sub-client exists the moment you create it and can do nothing until it is verified. This is the only lifecycle that gates every other one — no account is opened and no money moves until it reaches a terminal approval.

​
What advances it

You do not drive these transitions. What you control is the data: submit it complete, and fix it with an update when something is wrong.
Branch on status. It is the sub-client’s lifecycle, and the field the table above describes. verification_status reports the result of the identity check itself — useful to display, not the one to gate a flow on.

​
What announces it

A rejection tells you it happened, not what to fix. user.verification.failed carries data.reasons[] and no read of the sub-client returns it, so capture it on arrival — but expect a short label, not a compliance explanation. What you act on is missing_fields, and an RFI when something specific is needed.

​
Where an RFI interrupts it

A request for information is raised when something more is needed. It is not a failure — it is the check asking rather than declining. The item is the unit: an RFI can have several, each answered separately, and one returned item does not undo the others. Answering one sends you nothing back.
A document rejected on its own does not move status. When a check cannot finish until something is resupplied, verification_status reads needs_action and status stays where it was. Read verification_status to know that something is waiting on you — see User values.
A URL with no event filter receives rfi.* along with everything else. A URL with a filter receives it only if the filter names these events. Webhooks overview has the subscription rules. Design for this from the start. An RFI is answered by your customer, not by your engineers, so the fields it names have to reach whoever can supply them.

​
What to build

  1. Listen for user.status_changed and treat it as the source of truth for where a sub-client is.
  2. Capture data.reasons[] from user.verification.failed on arrival. You cannot go back for it.
  3. Surface missing_fields from the sub-client to whoever can act on it.
  4. Have a path for an RFI before you have one.

Account opening

Turning an approved sub-client into an account that can receive money.