--- updatedAt: 2026-09-17T13:50:57.000Z agentTools: projectIndex: https://docs.sumsub.com/llms.txt --- # Generate external WebSDK link # Overview Use this method to generate an external link ([permalink](https://docs.sumsub.com/sumsub/docs/verification-links#use-permalinks)) to the [WebSDK](https://docs.sumsub.com/sumsub/docs/web-sdk) for a specific applicant. Optionally, you can define post-verification redirect behavior by including the `redirect` parameter in the request. This allows you to specify custom URLs for successful or failed verification outcomes. ## Required permissions To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **Create applicants** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions). ## Request examples ```curl For applicant curl -X POST \ 'https://api.sumsub.com/resources/sdkIntegrations/levels/-/websdkLink?lang=en&source=dashboardFlows&customizationName=SomeCustomization&translationName=SomeTranslation' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "levelName": "level-name", "userId": "cool-external-user-id", "applicantIdentifiers": { "email": "email@email.com", "phone": "+4400000000000" }, "redirect": { "successUrl": "https://website/zdf;jzgxhd;fibzh;dfihb;kdsh;vzu?status=ok", "rejectUrl": "https://website/zdf;hzidxh54o8yw49ah489gh;drughr?status=reject", "signKey" : "dzihgsiKUH786769p", "allowedQueryParams": [ "param1", "param2", "param3", "param4" ] }, "ttlInSecs": 1800 }' ``` ```curl For existing applicant action curl -X POST \ 'https://api.sumsub.com/resources/sdkIntegrations/levels/-/websdkLink?lang=en&translationName=SomeTranslation' \ -H 'content-type: application/json' \ -H 'X-App-Token: ' \ -H 'X-App-Access-Sig: ' \ -H 'X-App-Access-Ts: ' \ -d '{ "levelName": "action-level-name", "userId": "cool-external-user-id", "externalActionId": "86893ec9-d48c-496a-9f72-69e272ac84e9", "ttlInSecs": 3600 }' ``` # Response explained In the response, you will get a new link to the WebSDK. The following is a response example in case the request is sent and processed correctly: ```json { "url":"http://localhost:8092/websdk/p/7JwtC0pb9mcqQsLb" } ``` If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example: ```json { "description": "Request signature mismatch", "code": 401, "correlationId": "c0b20cfbbf674ce5aeaf479e72d33af8", "errorCode": 4003, "errorName": "app-token-signature mismatch" } ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "sumsub-api", "version": "1.0" }, "servers": [ { "url": "https://api.sumsub.com" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "X-App-Token", "in": "header", "x-default": "" } } }, "security": [ { "sec0": [] } ], "paths": { "/resources/sdkIntegrations/levels/-/websdkLink": { "post": { "summary": "Generate external WebSDK link", "description": "", "operationId": "generate-websdk-external-link", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "levelName", "ttlInSecs" ], "properties": { "levelName": { "type": "string", "description": "Name of the [verification level](https://docs.sumsub.com/sumsub/docs/verification-levels). The level determines the verification steps the applicant must complete and the [documents that are required](/reference/get-applicant-data#requirediddocs-attributes) for verification.

⚠️ Mind the following:
  • A level has to be created in the same [environment](https://docs.sumsub.com/sumsub/docs/sandbox-mode). For example, in the Sandbox mode, you may not be able to use a level configured to be only available in the Production environment.
  • A level name is case-sensitive. Kyc-level and kyc-level are considered as completely different level names. The system does not allow creating an applicant with the level name that does not exist.
  • The system does not allow creating a company profile with a level for individuals and vice versa.
" }, "userId": { "type": "string", "description": "Unique applicant identifier as registered on your side (`externalId`)." }, "externalActionId": { "type": "string", "description": "Identifier of the applicant action on your side.

ⓘ Required for existing applicant action." }, "applicantIdentifiers": { "type": "object", "description": "Contains the information about the applicant email address and phone number. When specified, the applicant email address and phone number will be automatically added to the applicant profile.", "properties": { "email": { "type": "string", "description": "Applicant email address." }, "phone": { "type": "string", "description": "Applicant phone number." } } }, "redirect": { "type": "object", "description": "Specifies redirect behavior after an applicant completes verification. This object lets you define where applicants are sent depending on the verification outcome, and optionally add security with JWT signing or preserve selected query parameters.", "required": [ "successUrl" ], "properties": { "successUrl": { "type": "string", "description": "Redirect URL after successful verification. Use this to bring applicants to your website or a custom success page once they pass verification.

⚠️ Maximum length: 1024 characters." }, "rejectUrl": { "type": "string", "description": "Redirect URL if verification fails. If not provided, applicants will not be redirected upon rejection.

⚠️ Maximum length: 1024 characters." }, "signKey": { "type": "string", "description": "Secret key for signing JWT (JSON Web Token). If set, overrides the default specified when configuring [WebSDK settings](https://cockpit.sumsub.com/checkus/devSpace/websdkKeySettings).

⚠️ Maximum length: 256 characters." }, "allowedQueryParams": { "type": "array", "description": "List of URL parameters to preserve and pass unchanged into the final redirect.

⚠️ Maximum allowed: 4 parameters.", "items": { "type": "string" } } } }, "ttlInSecs": { "type": "integer", "description": "Lifespan of the generated link in seconds. Default value is 30 mins.

⚠️ Maximum allowed value is `2592000` (30 days). Requesting a longer TTL does not return an error — it is silently capped to 30 days.", "default": 1800, "format": "int32" } } } } } }, "deprecated": false, "parameters": [ { "in": "query", "name": "lang", "schema": { "type": "string" }, "description": "[SDK language](https://docs.sumsub.com/sumsub/docs/supported-sdk-languages) specified using the ISO 639-1 code." }, { "in": "query", "name": "customizationName", "schema": { "type": "string" }, "description": "[Customization](https://cockpit.sumsub.com/checkus/sdkIntegrations/customizations/appearances) name." }, { "in": "query", "name": "translationName", "schema": { "type": "string" }, "description": "[SDK translation](https://cockpit.sumsub.com/checkus/sdkIntegrations/sdkTranslations) name." }, { "in": "query", "name": "source", "schema": { "type": "string", "enum": [ "websdk", "verificationEmail", "newBeneficiary", "dashboard", "dashboardPreview", "dashboardFlows", "unilink", "api" ] }, "description": "Source indicator. Available values: `websdk`, `verificationEmail`, `newBeneficiary`, `dashboard`, `dashboardPreview`, `dashboardFlows`, `unilink`, `api`." } ] } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```