> 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" %} **Not yet released (documentation preview)**: KYC OpenAPI has not been released to production. This documentation is for integration planning only; API definitions and business rules may change before release. Do not use it for production workloads. Contact MusePay to confirm test availability and access arrangements. Production availability will be announced separately. {% endhint %} {% hint style="warning" %} Every request must include the [common parameters](/reference/api-reference/common-parameters.md). The request example below shows business fields only. This endpoint initiates a chargeable verification request; read the [fee and in-progress request rules](/integration/kyc-api.md) first. {% endhint %} `POST` `/v1/kyc/link` Request a hosted verification link for an existing merchant user. For a new user, call [Create Applicant](/reference/api-reference/kyc-api/create-applicant.md) first. ## Request Body | Name | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | request\_id | String | Yes | Verification request identifier unique within your merchant account. Reuse only when retrying the same application, with unchanged business fields. Do not share it with other chargeable capabilities. | | user\_xid | String | Yes | Identifier of an existing user under your merchant account. | | level\_name | String | Yes | Canonical level: `L1`, `L2`, `L1_AML`, or `L2_AML`. Only enabled levels are allowed. Missing, blank, or unknown values are rejected; there is no default tier. Do not supply the provider's dashboard level name. | ## 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 | Verification request identifier, corresponding to `data.requestId` in the final merchant callback. | | fee\_order\_no | String | Fee order number for this verification. Persist it in your system. For fee reconciliation, call [Query Order](/reference/api-reference/acquiring-api/query-order.md) (`POST /v1/order/query`) with this number to check the fee order status and amount. | | user\_xid | String | Merchant-side user identifier. | | user\_id | String | MusePay user ID. | | level\_name | String | Level of this application, same as requested. | | kyc\_status | String | Application status; `PROCESSING` once created. See [Query KYC Status](/reference/api-reference/kyc-api/query.md) for subsequent states. | | kyc\_level | String | Highest verification level the user has already obtained through this product: `0`/`1`/`2`. Applying for a higher level does not raise it in advance, and this is not the final result of this application. | | link | String | Hosted verification link containing short-lived access credentials. Share only with the corresponding user; do not publish it or include it in 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 for verification. ## Processing rules * A new plain `L1`/`L2` application is rejected without generating a link or fee order if the user has already obtained the same or a higher identity level through this product. Query the current verification state instead. `L1` to `L2` upgrades and `L1` to `L1_AML` applications that add AML screening are allowed. AML applications are not treated as duplicates solely based on identity level and remain subject to enabled-level configuration. Same-level in-progress link renewal and request deduplication rules remain unchanged. * A successful response means a link was obtained, not that information was submitted or verification passed. Links are short-lived and should be opened promptly. Generating a link alone does not immediately create an applicant at the provider. * Only one verification application may be in progress for the same merchant and user across all levels. If the link expires or is lost, call this endpoint again with the same `user_xid` and the same `level_name` to **renew the link**: it returns a fresh link with the original `fee_order_no`, creates no new fee order and charges nothing, and the ongoing review is unaffected. Requesting a different level while an application is in progress is still rejected with `209002`; wait for the original application to complete or close first. * A card-issuing verification that is already in progress for the same user blocks this request with `209003`; wait for it to complete or close. This guard applies in this direction only and does not block card applications while a standalone application is running. * Accounts that operate card issuing are not eligible for this product, and this request is rejected without creating a fee order. User creation and status queries stay available, so the failure surfaces only here. See [Relationship to card KYC](/integration/kyc-api.md#relationship-to-card-kyc). * Retrying a successful request with the same `request_id` within the 1-hour deduplication window returns the original response without creating another fee order or extending link validity. Each HTTP request must still have a new `timestamp`, `nonce`, and signature. * The same `request_id` is rejected for in-progress or failed requests. After a timeout or failure, confirm the original request and fee order outcome first. If a new application is needed, use a new identifier only after confirming that no order remains in progress. Replay is not guaranteed outside the window. * Both approval and final rejection settle the fee. Requests for additional information are not final results. Link generation failure initiates order closure and fund release, which may be delayed. * If a link expires while its application remains in progress, renew it as described above; no need to contact MusePay, and do not apply again with a different level or user identifier. Contact MusePay only if a renewed link still fails to open or query results look inconsistent. Results: [KYC Merchant Webhook](/integration/webhook/kyc.md) and [Query KYC Status](/reference/api-reference/kyc-api/query.md).