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. It is useful to display, but it is 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[], which only the event holds. Event catalog says how to keep them. 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. rfi.raised tells you one exists. The sub-client’s verification waits until the request closes. RFI covers the events, what each carries, and how to answer.
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.
Event catalog says which URLs receive rfi.*. Design for this from the start. Your customer answers an RFI, not 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, as the Event catalog says.
  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.