> For the complete documentation index, see [llms.txt](https://docs.musepay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.musepay.io/reference/api-reference/kyc-api/link.md).

# Get Verification Link

{% hint style="warning" %}
Every request must include the [common parameters](https://docs.musepay.io/reference/api-reference/common-parameters.md). The example below shows business fields only.
{% endhint %}

<mark style="color:green;">`POST`</mark> `/v1/kyc/link`

Starts one chargeable verification and returns a hosted link. Call [Create Applicant](https://docs.musepay.io/reference/api-reference/kyc-api/create-applicant.md) first for a new user.

## Request Body

| Name        | Type   | Required | Description                                                                                                                           |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| request\_id | String | Yes      | Identifies this application within your merchant account. Reuse it only to retry the same application with unchanged business fields. |
| user\_xid   | String | Yes      | An existing user under your merchant account.                                                                                         |
| level\_name | String | Yes      | `L1`, `L2`, `L1_AML`, or `L2_AML`. Only enabled levels are accepted; there is no default.                                             |

## Request Example

```json
{
  "request_id": "kyc-link-202610150001",
  "user_xid": "customer-0001",
  "level_name": "L1"
}
```

## Response Body

The following fields are returned in `data`.

| Name           | Type   | Description                                                                                                                                                                                     |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| request\_id    | String | Application identifier, equal to `data.requestId` in the final callback.                                                                                                                        |
| fee\_order\_no | String | Fee order for this verification. Persist it; check status and amount with [Query Order](https://docs.musepay.io/reference/api-reference/acquiring-api/query-order.md) (`POST /v1/order/query`). |
| user\_xid      | String | Merchant-side user identifier.                                                                                                                                                                  |
| user\_id       | String | MusePay user ID.                                                                                                                                                                                |
| level\_name    | String | Level of this application, as requested.                                                                                                                                                        |
| kyc\_status    | String | `PROCESSING` once created. Later states are in [Query KYC Status](https://docs.musepay.io/reference/api-reference/kyc-api/query.md).                                                            |
| kyc\_level     | String | Highest level already obtained through this product: `0`/`1`/`2`. Requesting a higher level does not raise it in advance.                                                                       |
| link           | String | Hosted verification link with short-lived credentials. Share it only with the corresponding user and keep it out of public logs.                                                                |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyc-link-202610150001",
    "fee_order_no": "2026101500000000000000000001",
    "user_xid": "customer-0001",
    "user_id": "1000001",
    "level_name": "L1",
    "kyc_status": "PROCESSING",
    "kyc_level": "0",
    "link": "https://in.sumsub.com/websdk/p/EXAMPLE_TOKEN"
  }
}
```

The example link is a placeholder and cannot be used.

## Behaviour

* A successful response means a link exists, not that the user submitted information or passed. Open it promptly.
* One application per user across all levels. Renewing means calling this endpoint again with the same `user_xid` and the same `level_name`: you get a fresh link and the original `fee_order_no`, with no new fee order and no new charge. Requesting a different level while one is running returns `209002`.
* A plain `L1`/`L2` request for a user who already holds that level or higher returns `209004` without a link or fee order. Upgrading `L1` → `L2` and adding screening `L1` → `L1_AML` are allowed.
* A user already handled by card-issuing KYC returns `209003`. Accounts that operate card issuing are not eligible for this product; see [Relationship to card KYC](https://docs.musepay.io/integration/kyc-api.md#relationship-to-card-kyc).
* Retrying a successful request with the same `request_id` within one hour returns the original response, without a new fee order or longer link validity. Regenerate `timestamp`, `nonce`, and `sign` for each attempt.
* Within that same hour an attempt that failed or is still running is not re-executed: the `request_id` comes back as a duplicate-request error. Confirm the original outcome first, and use a new `request_id` only once you know no order is in progress.

Results arrive through the [KYC Webhook](https://docs.musepay.io/integration/webhook/kyc.md) and can be read at any time with [Query KYC Status](https://docs.musepay.io/reference/api-reference/kyc-api/query.md).
