> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pods.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How Pods KYC works end to end: providers and flows, onboarding endpoints, one status model, and retention

Pods KYC normalizes several identity and verification flows behind a single status model so your application can enable fiat-to-crypto money movement without integrating each local KYC/AML provider yourself. You pick the flow that fits your users, onboard them, and poll one status endpoint until a capability is unlocked.

<Info>
  Whatever flow you use, approval is asynchronous and every profile is customer-scoped. Poll `GET /api/v1/kyc/status` until the profile reaches a terminal state and the capability flag you need (`brlaEnabled` for Brazil, `usdEnabled` for foreign USD) is `true`.
</Info>

## Introduction

| Item                     | Value                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flows / providers**    | Sumsub reusable KYC (Brazil Pix), external evidence (bring-your-own capture), foreign USD (Sumsub → Avenia), age verification (BigID hosted iframe)                  |
| **Onboarding endpoints** | `POST /api/v1/kyc/sumsub-share-token` · `POST /api/v1/kyc/foreign/sumsub-share-token` · `POST /api/v1/kyc/sessions` + `/submit` · `POST /api/v1/kyc/currency-unlock` |
| **Status endpoint**      | `GET /api/v1/kyc/status?kycUserId=…`                                                                                                                                 |
| **Terminal statuses**    | `approved`, `rejected`, `rejected_retryable`, `blocked`                                                                                                              |
| **Capability flags**     | `brlaEnabled` (Brazil), `usdEnabled` (foreign USD), `eurEnabled` (planned)                                                                                           |
| **Retention**            | Document/selfie images are never stored; the rest of an external-evidence payload is kept up to 7 days for retry                                                     |
| **Auth**                 | Header `x-api-key: <your-key>`                                                                                                                                       |

## Authentication

Every request requires:

```
x-api-key: <your-api-key>
```

* The key identifies your **customer**. Fee configuration and strategy catalog are scoped to it.
* Success responses are the bare JSON body (HTTP 200). Errors use `{ "error": { "code", "message", "details?" } }`.
* Keep the API key on your **backend** — never expose it in a browser app.

Don't have a key yet? [Get an API key](https://www.pods.finance/plg/select-plan).

## Integration flow

<Steps>
  <Step title="Choose your KYC flow">
    Pick the flow that matches your users: bring-your-own capture (external evidence), foreign USD onboarding, or Brazil Pix Sumsub reusable KYC.
  </Step>

  <Step title="Onboard the applicant">
    Create a session and submit the evidence you captured, or submit a Sumsub reusable share token — depending on the flow. Each call returns a `kycUserId` — store it for status polling.

    **External evidence**

    ```http theme={null}
    POST /api/v1/kyc/sessions   # then POST /submit
    ```

    Full guide: [External evidence KYC](/guides/kyc/external-evidence)

    **Brazil Pix reusable KYC**

    ```http theme={null}
    POST /api/v1/kyc/sumsub-share-token
    ```

    Full guide: [Set up Pods Ramp](/guides/ramp/setup)

    **Foreign USD**

    ```http theme={null}
    POST /api/v1/kyc/foreign/sumsub-share-token
    ```

    Full guide: [Foreign USD KYC and ramps](/guides/kyc/usd-foreign-ramp)
  </Step>

  <Step title="Poll status">
    Verification is asynchronous. Poll until the profile reaches a terminal state:

    ```http theme={null}
    GET /api/v1/kyc/status?kycUserId=550e8400-e29b-41d4-a716-446655440000
    ```

    Full guide: [Track Pods Ramp status](/guides/ramp/status).
  </Step>

  <Step title="Unlock capability (foreign USD)">
    Level 1 approval does not enable USD ramps by itself. Request the currency unlock and poll status until `usdEnabled` is `true`:

    ```http theme={null}
    POST /api/v1/kyc/currency-unlock
    ```

    Full guide: [Foreign USD KYC and ramps](/guides/kyc/usd-foreign-ramp).
  </Step>

  <Step title="Move money">
    Once the capability flag is `true`, use the same Swap v2 quote routes to onramp, offramp, or ramp to yield:

    ```http theme={null}
    GET /v2/swap/quote
    ```

    Full guide: [Move money with Pods Ramp](/guides/ramp/quotes).
  </Step>
</Steps>