> For a complete page index, fetch https://docs.transak.com/llms.txt

# Transak KYC using APIs

This document provides a detailed explanation of KYC flows, covering Simple KYC, Standard KYC and Enhanced KYC, along with the required API interactions and processes. KYC is a mandatory step in compliance with regulatory requirements before users can place orders on Transak.

## KYC Flow Chart

| **KYC Type**     | **Requirements**                                                                                                                                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Simple KYC**   | Personal Details, Address Details, SSN (for US users only), FCA (for UK users only) (not available to EEA users)                                                                                                                   |
| **Standard KYC** | Personal Details, Address Details, SSN (for US users only), FCA (for UK users only), MiCA Consent (for EEA users who completed KYC before MiCA), Source of Income (for EEA users), ID Proof Upload, Liveness Check (Selfie)        |
| **Enhanced KYC** | Personal Details, Address Details, SSN (for US users only), FCA (for UK users only), MiCA Consent (for EEA users who completed KYC before MiCA), Source of Income, Proof Document Upload, ID Proof Upload, Liveness Check (Selfie) |

## Fetch KYC Requirement Based on Quote ID

The **KYC requirements** are determined dynamically using the quote ID. Transak supports multi-level KYC, meaning different users may have different requirements based on country, regulations, and transaction limits.

When fetching **KYC Requirement**, there can be four statuses:

| **KYC Status**            | **Description**                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| APPROVED                  | KYC is done and approved by Transak. User can proceed with the order creation flow.                    |
| SUBMITTED                 | KYC personal and address details or additional forms are submitted.                                    |
| NOT_SUBMITTED             | KYC personal and address details are not submitted.                                                    |
| ADDITIONAL_FORMS_REQUIRED | All details are submitted but some more additional requirements need to be fulfilled for KYC approval. |

* **Personal Details** → First name, last name, mobile number, and date of birth.
* **Address Details** → User's residential details (address, city, state, zip code).
* **Purpose of Usage** → Used for compliance with regulations.
* **ID Proof** → Required only if **Standard or Enhanced KYC** is needed.
* **SSN** → Required only for **US KYC** users.
* **FCA** → Required only for **UK KYC** users.
* **MiCA Consent** → Required only for existing **EEA KYC** users who completed KYC before MiCA.
* **Source of Income** → Required if **Enhanced KYC** is needed, and for all **EEA KYC** users (with employment status and nationality).
* **Proof Document** → Required only if **Enhanced KYC** is needed.

All forms must be submitted in the sequence provided in the **Get Additional Requirements** API.

## KYC Flow - Step-by-Step Guide

#### Fetch KYC Status

Call [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement) with the `quoteId` to fetch current status of the user's KYC.

<table>
  <thead>
    <tr>
      <th>
        Condition
      </th>

      <th>
        Next step
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `data.kyc.status` = **APPROVED**
      </td>

      <td>
        Move forward with the **Create Order Flow**
      </td>
    </tr>

    <tr>
      <td>
        `data.kyc.status` = **NOT_SUBMITTED**
      </td>

      <td>
        Follow **Step 2**
      </td>
    </tr>

    <tr>
      <td>
        `data.kyc.status` = **ADDITIONAL_FORMS_REQUIRED**
      </td>

      <td>
        Follow **Step 3**
      </td>
    </tr>
  </tbody>
</table>

> **Info**
>
> **EEA users:** a user who was `APPROVED` before MiCA can return `ADDITIONAL_FORMS_REQUIRED` or `NOT_SUBMITTED` until they complete the MiCA steps or a KYC refresh. Do not cache the KYC status. Call this step with a fresh `quoteId` before every order.

#### Patch User Details

Call [Patch User Details](/api/whitelabel/kyc/patch-user-details) to collect and submit the user's personal and address information.

Once submitted, return to **Step 1** to re-fetch the updated KYC status.

#### Get Additional Requirements

Call [Get Additional Requirements](/api/whitelabel/kyc/get-additional-requirements) to check which forms still need to be completed.

Check if additional information must be provided for KYC Approval. Multiple forms may appear and must be submitted **in the sequence provided** in the API response:

1. If `type = PURPOSE_OF_USAGE` → Follow **Step 4**
2. If `type = IDPROOF` → Follow **Step 5**
3. If `type = US_SSN` → Follow **Step 6**
4. If `type = FCA` → Follow **Step 7**
5. If `type = CONSENT` → Follow **Step 8**
6. If `type = SOURCE_OF_INCOME` → Follow **Step 9**
7. If `type = DOCUMENT_PROOF` → Follow **Step 10**

#### MiCA forms for EEA users

**1. `CONSENT` is usually returned first.** Existing EEA users get the `CONSENT` form. Process forms in the order they are returned. New EEA users, who complete KYC after MiCA, never get `CONSENT`: their first forms are the usual ones, such as `PURPOSE_OF_USAGE`.

```json
{
  "data": {
    "formsRequired": [
      { "type": "CONSENT" }
    ]
  }
}
```

After the consent is submitted in **Step 8**, call **Get Additional Requirements** again to get the next forms. Do this after each form you submit: more forms (for example `IDPROOF`) can appear until **Get KYC Requirement** returns `APPROVED`.

**2. `SOURCE_OF_INCOME` has extra options for EEA users.** Besides the source of funds options, `metadata` includes `employmentStatusOptions` and `countryOfCitizenshipOptions`. Build a dropdown from each list and send the selected `value` in **Step 9**.

Transak decides whether a new user is an EEA user from the address country sent in **Step 2** (Patch User Details), not from the fiat currency. Until an EEA address is submitted, the `SOURCE_OF_INCOME` form and its EEA options are not returned, so call **Get Additional Requirements** again after Step 2.

```json
{
  "data": {
    "formsRequired": [
      {
        "type": "SOURCE_OF_INCOME",
        "metadata": {
          "sourceOfFundsTypeOptions": [
            { "name": "Salary payments", "value": "salary_payment" }
          ],
          "employmentStatusOptions": [
            { "name": "Student", "value": "student" },
            { "name": "Retired", "value": "retired" },
            { "name": "Unemployed", "value": "unemployed" },
            { "name": "Self Employed", "value": "self_employed" },
            { "name": "Junior/Entry-Level Employee", "value": "junior_entry_level_employee" },
            { "name": "Mid-Level Employee", "value": "mid_level_employee" },
            { "name": "Management Role", "value": "management_role" },
            { "name": "Executive Role", "value": "executive_role" }
          ],
          "countryOfCitizenshipOptions": [
            { "name": "Austria", "value": "AT" },
            { "name": "Germany", "value": "DE" },
            { "name": "India", "value": "IN" }
          ]
        }
      }
    ]
  }
}
```

| Options                       | Values                                                                                                                                                                                                                                                                           |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceOfFundsTypeOptions`    | `salary_payment`, `savings`, `property_sale`, `sale_of_crypto`, `inheritance`, `pension`, `loan`, `dividends`, `gift_or_donation`, `income_from_services_provided`, `stock_share_sale` (shortened in the example above). `options` carries the same list for older integrations. |
| `employmentStatusOptions`     | `student`, `retired`, `unemployed`, `self_employed`, `junior_entry_level_employee`, `mid_level_employee`, `management_role`, `executive_role`                                                                                                                                    |
| `countryOfCitizenshipOptions` | All countries, as ISO 3166-1 alpha-2 codes (for example `DE`, `FR`, `IN`). The user can be a national of any country, not only an EEA country. Shortened in the example above.                                                                                                   |

EEA users submit `employmentStatus` and `countryOfCitizenship` on the `SOURCE_OF_INCOME` form, together with the source of funds. They do not get a separate form for these fields.

**3. ID proof may be requested again.** If the user's ID document has expired or their KYC is older than 12 months, `IDPROOF` can be returned. Handle it as in **Step 5**.

MiCA Changes for EEA Users

#### Post Purpose of Usage

Call [Update Purpose of Usage](/api/whitelabel/kyc/update-purpose-of-usage) to record the user's reason for buying crypto.

#### Complete ID Proof & Liveness Check (For Standard KYC)

Redirect the user to the `Transak-hosted KYC Widget` using the `kycUrl` returned in the Additional Requirements response.

<table>
  <tbody>
    <tr>
      <td>
        **`ID Proof Upload`** `action`

        Upload a photo ID — Passport, Driver's License, or National ID

        ---

        **`Liveness Check`** `action`

        Submit a selfie for real-time identity validation

        ---
      </td>
    </tr>
  </tbody>
</table>

#### Submit SSN (US Users Only)

Call [Submit SSN](/api/whitelabel/kyc/submit-ssn) to validate the user's identity using their Social Security Number.

#### Submit FCA (UK Users Only)

FCA (Financial Conduct Authority) compliance is required for all UK users. The flow covers three sequential steps — investor categorization, a compliance agreement, and a risk assessment.

See the dedicated guide for the full API sequence, status handling, and step-by-step integration details:

How to Submit KYC FCA Requirements

#### Submit MiCA Consent (EEA Users Only)

EEA users who completed KYC before MiCA must give a one-time MiCA consent. Show the consent screen, then call [Submit MiCA Consent](/api/whitelabel/kyc/submit-mica-consent) with the time the user agreed.

MiCA Changes for EEA Users

#### Submit Source of Income (For Enhanced KYC and EEA Users)

Call [Submit Source of Income](/api/whitelabel/kyc/submit-source-of-income) to capture the user's primary income source. Required for higher transaction limits, and for all EEA users. EEA users must also send `employmentStatus` and `countryOfCitizenship`.

#### Upload Proof Document (For Enhanced KYC)

Call [Upload Proof Document](/api/whitelabel/kyc/upload-proof-document) to submit supporting documentation for the income source selected in the previous step.

## Different KYC Levels Guide

| KYC Type   | KYC Status    | User Status | Action                                                                                                                                                                     |
| ---------- | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `null`     | NOT_SUBMITTED | ACTIVE      | Call **GET KYC Requirement API** → Complete KYC Forms                                                                                                                      |
| `SIMPLE`   | SUBMITTED     | ACTIVE      | Poll **GET User Details API**                                                                                                                                              |
| `SIMPLE`   | APPROVED      | ACTIVE      | Call **GET KYC Requirement API** → If `APPROVED` place order → If `ADDITIONAL_FORMS_REQUIRED` call Get Additional Requirements API → If `NOT_SUBMITTED` patch user details |
| `SIMPLE`   | REJECTED      | ACTIVE      | Call **GET KYC Requirement API** → If `ADDITIONAL_FORMS_REQUIRED` call Get Additional Requirements API → If `NOT_SUBMITTED` patch user details                             |
| `STANDARD` | SUBMITTED     | ACTIVE      | Poll **GET User Details API**                                                                                                                                              |
| `STANDARD` | APPROVED      | ACTIVE      | Call **GET KYC Requirement API** → If `APPROVED` place order → If `ADDITIONAL_FORMS_REQUIRED` call Get Additional Requirements API                                         |
| `STANDARD` | REJECTED      | ACTIVE      | Call **GET KYC Requirement API** → If `APPROVED` place order → If `ADDITIONAL_FORMS_REQUIRED` call Get Additional Requirements API → If `NOT_SUBMITTED` patch user details |
| `STANDARD` | REJECTED      | DISABLED    | Show static screen — Contact Support                                                                                                                                       |
| `ENHANCED` | SUBMITTED     | ACTIVE      | Poll **GET User Details API**                                                                                                                                              |
| `ENHANCED` | APPROVED      | ACTIVE      | Call **GET KYC Requirement API** → If `APPROVED` place order                                                                                                               |
| `ENHANCED` | REJECTED      | ACTIVE      | Call **GET KYC Requirement API** → If `APPROVED` place order → If `ADDITIONAL_FORMS_REQUIRED` call Get Additional Requirements API → If `NOT_SUBMITTED` patch user details |
| `ENHANCED` | REJECTED      | DISABLED    | Show static screen — Contact Support                                                                                                                                       |

## API Overview

#### [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement)

Returns the user's KYC status for a quote: what is approved and what is still needed.

#### [Get Additional Requirements](/api/whitelabel/kyc/get-additional-requirements)

Returns the forms the user still has to submit, in the order to submit them.

#### [Patch User Details](/api/whitelabel/kyc/patch-user-details)

Submits the user's personal and address details.

#### [Update Purpose of Usage](/api/whitelabel/kyc/update-purpose-of-usage)

Submits why the user is buying crypto.

#### [Get KYC IdProof Status](/api/whitelabel/kyc/get-kyc-idproof-status)

Returns the status of the ID proof and liveness check.

#### [Submit SSN](/api/whitelabel/kyc/submit-ssn)

US users: submits the Social Security Number.

#### [Submit MiCA Consent](/api/whitelabel/kyc/submit-mica-consent)

EEA users: submits the MiCA consent.

#### [Submit Source of Income](/api/whitelabel/kyc/submit-source-of-income)

Submits the source of funds (and, for EEA users, employment status and nationality).

#### [Upload Proof Document](/api/whitelabel/kyc/upload-proof-document)

Enhanced KYC: uploads the proof document.

See [Error Codes](/api/whitelabel/error-codes) for the KYC errors (`30xx`) these APIs return.