POST

Initiate Sumsub IDV for a user

Initiates the Sumsub identity verification flow for a user within an enterprise. Returns a WebSDK URL when verification is pending, or a completion status if the user has already been verified.

Body Params

object

userId string required

The BitGo user ID
enterpriseId string required

The BitGo enterprise ID
verificationType string enum required

The verification flow to use. 'penny-drop' requires a bank transfer step. 'video-id' uses a video identification step. 'liveness-only' uses a liveness check only.

penny-dropvideo-idliveness-only
sumsubShareToken string

Share token to copy an existing applicant from another Sumsub environment

at least 1 characters
lang string enum

Language code for the Sumsub WebSDK UI (ISO 639-1). Defaults to en.

arhyazbnbgmycakmzhzh-twhrcsdanlenetflfifrkadeelhahehihuiditjakkkololvltmsnofaplptpt-brrorusrskslesswsvtgtrthukuruzvizu
includeSdkToken boolean

When true, generates and returns a Sumsub Mobile SDK access token alongside the WebSDK URL. Not supported for penny-drop verification — returns 400 if combined with verificationType 'penny-drop' (MobileSDK does not support the penny-drop flow).

Responses

200

Response Body

ONE OF

idvId string required
status string enum required

pending
url string required
expiresAt string required
sdkToken string

idvId string required
status string enum required

action_required
url string required
expiresAt string required
sdkToken string

idvId string required
status string enum required

approved

idvId string required
status string enum required

rejected

400

Response Body

object

error string required

Error message

403

Response Body

object

error string required

Error message

500

Response Body

object

error string required

Error message

curl --request POST \ --url 'https://app.bitgo-test.com/api/sumsub-service/v1/idv' \ --header 'accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --data '{,"userId":"string","enterpriseId":"string","verificationType":"penny-drop","sumsubShareToken":"string","lang":"ar","includeSdkToken":true}'

const url = 'https://app.bitgo-test.com/api/sumsub-service/v1/idv'; const options = { method: 'POST', headers: {accept: 'application/json', 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'content-type': 'application/json'}, body: JSON.stringify({,"userId":"string","enterpriseId":"string","verificationType":"penny-drop","sumsubShareToken":"string","lang":"ar","includeSdkToken":true}) }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));

require 'uri' require 'net/http' url = URI("https://app.bitgo-test.com/api/sumsub-service/v1/idv") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["accept"] = 'application/json' request["Authorization"] = 'Bearer YOUR_ACCESS_TOKEN' request["content-type"] = 'application/json' request.body = '{,"userId":"string","enterpriseId":"string","verificationType":"penny-drop","sumsubShareToken":"string","lang":"ar","includeSdkToken":true}' response = http.request(request) puts response.read_body

<?php require_once('vendor/autoload.php'); $client = new \GuzzleHttp\Client(); $response = $client->request('POST', 'https://app.bitgo-test.com/api/sumsub-service/v1/idv', [ 'headers' => [ 'accept' => 'application/json', 'Authorization' => 'Bearer YOUR_ACCESS_TOKEN', 'content-type' => 'application/json', ], 'body' => '{,"userId":"string","enterpriseId":"string","verificationType":"penny-drop","sumsubShareToken":"string","lang":"ar","includeSdkToken":true}', ]); echo $response->getBody();

import requests url = "https://app.bitgo-test.com/api/sumsub-service/v1/idv" payload = {,"userId":"string","enterpriseId":"string","verificationType":"penny-drop","sumsubShareToken":"string","lang":"ar","includeSdkToken":true} headers = { "accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN", "content-type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text)