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

# KYC Overview

> What Etherfuse collects to verify a customer, how to track where their verification stands, and the extra requirements that apply in specific countries.

Every customer must clear identity verification before their wallet can transact.

## Choosing a flow

| Flow                                                       | You submit                                                                                                                   | Customer submits                                                                                         |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [**KYC WebSDK**](/guides/kyc-websdk) (the default)         | Nothing                                                                                                                      | Everything                                                                                               |
| [**KYC API**](/guides/kyc-api)                             | Personal data, identity document, questionnaire answers, and any [region-specific documents](#country-specific-requirements) | Email confirmation, liveness selfie, customer agreement                                                  |
| [**Sumsub shared token**](/guides/kyc-sumsub-shared-token) | A share token, then questionnaire answers and any [region-specific documents](#country-specific-requirements)                | The customer agreement, plus email confirmation or liveness only if the shared session didn't cover them |

## Requirements List

| Requirement          | What satisfies it                                                                                                                                          | How it can be submitted     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `personal_data`      | Name, date of birth, tax id, country, and residential address.                                                                                             | WebSDK · API · Shared token |
| `identity_document`  | A government-issued photo ID. Any valid one works.                                                                                                         | WebSDK · API · Shared token |
| `proof_of_address`   | A utility bill, bank statement, tax bill, employment certificate, property deed, or invoice. Requested only when the identity document carried no address. | WebSDK · API · Shared token |
| `occupation`         | Job title and an occupation category.                                                                                                                      | WebSDK · API                |
| `email_confirmation` | The customer confirming the email you registered on their organization.                                                                                    | WebSDK · Shared token       |
| `selfie`             | A live face capture.                                                                                                                                       | WebSDK · Shared token       |
| `customer_agreement` | The customer accepting Etherfuse's agreements.                                                                                                             | WebSDK                      |

Some countries add specific additional requirements. See [Country-specific requirements](#country-specific-requirements).

## Tracking verification status

### The overall status

<CodeGroup>
  ```bash Sandbox theme={null}
  curl -H "Authorization: <api_key>" \
    https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/kyc
  ```

  ```bash Production theme={null}
  curl -H "Authorization: <api_key>" \
    https://api.etherfuse.com/ramp/customer/<customer_uuid>/kyc
  ```
</CodeGroup>

```json theme={null}
{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "submitted",
  "currentRejectionReason": null,
  "needsWork": false,
  "approvedAt": null
}
```

| Status        | Description                                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `not_started` | No verification started                                                                                              |
| `in_progress` | Started, but not everything is submitted. Detail in `needsWork` and `userMessage`                                    |
| `submitted`   | Submitted, awaiting review (manual or automated)                                                                     |
| `approved`    | Cleared; the customer can transact                                                                                   |
| `denied`      | A rejected verdict, or a previously-approved customer whose approval was revoked. Reason in `currentRejectionReason` |

### The per-requirement breakdown

Add **`?requirements=true`** for a step-by-step account of what the customer still needs. It is opt-in: omit the parameter and the response is unchanged.

```bash theme={null}
curl "https://api.sand.etherfuse.com/ramp/customer/<customer_uuid>/kyc?requirements=true" \
  -H "Authorization: <api_key>"
```

```json theme={null}
{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "in_progress",
  "requirements": [
    { "type": "personal_data",      "status": "satisfied", "requiresLaunch": false },
    { "type": "identity_document",  "status": "satisfied", "requiresLaunch": false },
    { "type": "occupation",         "status": "pending",   "requiresLaunch": false },
    { "type": "email_confirmation", "status": "pending",   "requiresLaunch": true  },
    { "type": "selfie",             "status": "pending",   "requiresLaunch": true  },
    { "type": "customer_agreement", "status": "pending",   "requiresLaunch": true  }
  ]
}
```

Each `type` matches a requirement in the [Requirements List](#requirements-list) or a [country-specific](#country-specific-requirements) one. `requiresLaunch: true` marks the rows only the WebSDK can satisfy.

<Warning>
  **`requirements` is absent until the customer has been routed to their country's requirements**, so it is missing immediately after their personal data is submitted. Read it again a moment later. It also **grows**: `proof_of_address` appears only at a later stage, and only when the identity document carried no address.
</Warning>

<Note>
  We reserve the right to add new requirements, and will update these docs when we do. Some countries may also gain requirements of their own.
</Note>

### Requirement statuses

| `status`          | Meaning                                 | What to do                |
| ----------------- | --------------------------------------- | ------------------------- |
| `satisfied`       | Accepted.                               | Nothing.                  |
| `pending`         | Nothing has been provided for this yet. | Supply it.                |
| `awaiting_review` | Provided, not yet reviewed.             | Wait.                     |
| `action_required` | **Reviewed and rejected.**              | Send it again, corrected. |

## Country-specific requirements

<AccordionGroup>
  <Accordion title="🇲🇽 Mexico">
    | Requirement    | What satisfies it                                                              | How it can be submitted |
    | -------------- | ------------------------------------------------------------------------------ | ----------------------- |
    | `tax_document` | The **Constancia de Situación Fiscal**, the tax-status document issued by SAT. | WebSDK · API            |

    It must be legible and belong to the customer being verified. Submit it as the `tax_document` part of [`POST /ramp/customer/{customer_id}/verification/documents`](/api-reference/kyc/upload-verification-documents), or let the customer upload it in the widget.

    <Info>
      **In sandbox, the constancia is the one document that has to look real.** Any real constancia with any data in it works. Use [this example constancia](https://stablebonds.s3.us-west-2.amazonaws.com/example-constancia-de-situacion-fiscal.pdf).
    </Info>
  </Accordion>
</AccordionGroup>

## Reference

<Expandable title="Bank account status">
  A bank account must be **`active`** before you can create orders against it. Check the `status` in the registration response or via [GET /ramp/bank-accounts](/api-reference/bank-accounts/list-bank-accounts); a [`bank_account_updated`](/guides/verifying-webhooks) webhook fires when it changes.

  <Info>In **sandbox**, register the bank account with the placeholder RFC `XEXX010101000` to mark it `active` immediately. Any other RFC is treated as a real registration and will not auto-approve.</Info>
</Expandable>

<Expandable title="Webhooks">
  Register a webhook for `kyc_updated` events to receive status updates. See [POST /ramp/webhook](/api-reference/webhooks/create-webhook) for setup and payload details.

  **Approved:**

  ```json theme={null}
  {
    "kyc_updated": {
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "walletPublicKey": "9Qx7r...",
      "status": "approved",
      "approved": true,
      "updateReason": "KYC approved"
    }
  }
  ```

  **Denied:**

  ```json theme={null}
  {
    "kyc_updated": {
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "walletPublicKey": "9Qx7r...",
      "status": "denied",
      "approved": false,
      "updateReason": "Identity verification could not be completed."
    }
  }
  ```
</Expandable>

<Expandable title="Data isolation">
  Partners can only access KYC data they submitted:

  | Accessor              | Data Visibility                                            |
  | --------------------- | ---------------------------------------------------------- |
  | Partner (via API key) | Only data where `source_organization_id` matches their org |
  | Wallet Owner          | All data for their wallet                                  |
  | Admin                 | All data                                                   |

  This prevents partners from accessing PII submitted by other partners or directly by users.
</Expandable>