> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trevex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trevex.io/_mcp/server.

# 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`](/api-reference/kyb-requests/resubmit-claim)
and pass only the fields you want to change - anything you omit is copied from
the original draft.

> **Info**
>
> 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`](/api-reference/kyb-requests/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.