# KYC flow

Most flows require validating a user’s Know Your Customer (KYC) level before creating an order. The high-level steps are:

1. Call [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) with a user’s email and a country.
2. Inspect the returned <mark style="color:yellow;">kycRules</mark> to see which KYC tier (<mark style="color:yellow;">basic</mark>, <mark style="color:yellow;">advanced</mark>, etc.) is required for the intended deposit or payout amounts and currency types.
3. If the user hasn’t already passed the needed tier (<mark style="color:yellow;">passedKycType</mark>), prompt them for the document listed in <mark style="color:yellow;">kycDocuments</mark> and gather the associated <mark style="color:yellow;">requiredFields</mark>.
4. Submit the collected data via [Submit user KYC](/server-to-server/api-endpoints/submit-user-kyc.md). Continue polling [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) until <mark style="color:yellow;">currentKycStatus</mark> becomes <mark style="color:yellow;">approved</mark>.

> Tip: The sample data below shows that payouts ≥ 100 USD in crypto require `advanced` KYC. Your environment will return thresholds appropriate for the country, currency, and operation type.

Sample [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) response

{% code overflow="wrap" expandable="true" %}

```json
{
  "passedKycType": null,
  "reachedKycLimit": false,
  "currentKycStatus": null,
  "currentKycStatusDescription": null,
  "kycDocuments": [
    {
      "_id": "67da909b739fc481aa525c43",
      "type": "basic",
      "title": "Voter ID",
      "value": "VOTER_ID",
      "requiredFields": [
        { "key": "first_name", "type": "string", "label": "First Name", "required": true },
        { "key": "last_name", "type": "string", "label": "Last Name", "required": true },
        { "key": "dob", "type": "date", "label": "Date of birth", "required": true },
        {
          "key": "id_number",
          "type": "string",
          "label": "ID number",
          "required": true,
          "format": "0000000000000000000",
          "regexp": "^[a-zA-Z0-9 ]{9,29}$",
          "regexpFlags": "i"
        }
      ]
    },
    {
      "_id": "67da93c0dfd3a00f3380b857",
      "type": "advanced",
      "title": "Driving License",
      "value": "DRIVERS_LICENSE",
      "requiredFields": [
        { "key": "first_name", "type": "string", "label": "First Name", "required": true },
        { "key": "last_name", "type": "string", "label": "Last Name", "required": true },
        { "key": "dob", "type": "date", "label": "Date of birth", "required": true },
        { "key": "images", "type": "smile-identity-images", "label": "Verification images", "required": true }
      ]
    }
  ],
  "kycRules": [
    {
      "operationType": "deposit",
      "currencyType": "crypto",
      "min": 0,
      "max": 100,
      "type": "basic"
    },
    {
      "operationType": "payout",
      "currencyType": "crypto",
      "min": 100,
      "max": "Infinity",
      "type": "advanced"
    }
  ]
}
```

{% endcode %}

The "<mark style="color:yellow;">advanced</mark>" KYC document requires images. Submit them as an array of objects with <mark style="color:yellow;">image\_type\_id</mark> and <mark style="color:yellow;">image</mark> URL. Image URLs must be publicly accessible or contain the image data as a base64-encoded string. The "<mark style="color:yellow;">image\_type\_id</mark>" can accept the following values:

* 0: Selfie
* 1: Document front
* 5: Document back

Sample <mark style="color:yellow;">Submit user KYC</mark> request

```json
{
  "userEmail": "someuser@example.com",
  "countryIsoCode": "NG",
  "documentId": "67da93c0dfd3a00f3380b857",
  "userFields": {
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1990-01-01",
    "images": [
      { "image_type_id": 0, "image": "https://cdn.com/selfie.jpg" },
      { "image_type_id": 1, "image": "https://cdn.com/front.jpg" },
      { "image_type_id": 5, "image": "https://cdn.com/back.jpg" }
    ]
  }
}
```

Once the user’s KYC status is approved at or above the required tier, proceed with quoting and order creation.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fonbnk.com/server-to-server/kyc-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.