KYB Request Lifecycle

Every KYB request moves through a small state machine. Knowing it helps you decide when to poll, when to retry, and when to show a final state to your user.

Status values

Status	Meaning
`pending_verification`	User has not yet verified their email
`under_review`	User is verified; awaiting admin decision
`approved`	Admin approved the KYB request. Webhook fires and the company is enrolled.
`rejected`	Admin declined the KYB request. Can be resubmitted via `resubmit_claim`.

End-to-end flow

Partner                          TREVEX                        User (requester)
-------                          ------                        ----------------
POST /upload_document/           Store file in S3
  (optional)                        |
        |                           | <- url
        v
POST /create_claim/
  (Api-Key auth)
        |
        v
    +----------------------------------+
    |  User exists?                    |
    |  YES -> user_verified: true      |-----------------------> (no action)
    |  NO  -> user_verified: false     |---- Verification email -> User clicks link
    +----------------------------------+                                 |
        |                                                                v
        |                                                     GET /verify_account/
        |                                                     Account created
        |                                                     Set-password email sent
        |                                                     Request unblocked
        v
    Admin reviews (under_review)
        |
        +--- Rejected --> POST /resubmit_claim/ (partner)
        |
        +--- Approved -> Webhook POST to partner
                         PATCH /update_claim/ (optional, partner)

Handling rejection

Only KYB requests with status rejected (internally Declined) can be resubmitted. Use resubmit_claim and pass only the fields you want to change - anything you omit is copied from the original draft.

Resubmission creates a new request_id. The old request_id is returned in the response as original_request_id so you can track the chain.

Polling vs webhooks

Approval is delivered both ways:

Webhook — fires on approval (your configured webhook_url). This is the recommended path.
Polling — call claim_status at a sensible interval (e.g. every few minutes) if you can’t expose a public webhook endpoint.

For rejected and pending_verification states, polling is currently the only signal.