---
title: "Initiate Sumsub wallet verification"
method: POST
path: "/counterparty/wallet-verification/sumsub/initiate"
tags: ["Counterparty"]
---

# Initiate Sumsub wallet verification

`POST /counterparty/wallet-verification/sumsub/initiate`

Starts (or refreshes) a Sumsub liveness flow for wallet verification on a declared self-hosted **OWNED** counterparty.

Provide `userId` and `counterpartyId` in the body, or call with a widget session token (values are taken from the session when omitted).

## Request body

- InitiateSumsubWalletVerificationRequest
  - `userId` string, uuid — User id. Provide exactly one of `userId` / `businessId`. Required when not using a widget session token; otherwise taken from the session.
  - `businessId` string, uuid — Business id. Provide exactly one of `userId` / `businessId`. Required when not using a widget session token; otherwise taken from the session.
  - `counterpartyId` string, uuid — Declared counterparty id. Required when not using a widget session token; otherwise taken from the session.

## Response `201`

success

- InitiateSumsubWalletVerificationResponse
  - `token` string, required — Sumsub access token for the liveness flow.
  - `expiresAt` string, date-time, required
  - `sumsubActionCreated` boolean, required — True when a new Sumsub applicant action was created (not a token refresh).
  - `walletVerificationId` string, uuid, required
  - `verificationLink` string, required — Direct URL to the Sumsub liveness verification flow for this wallet verification.

## Other responses

- `400` — Bad Request
- `401` — Invalid authentication header
- `404` — Counterparty not found
- `422` — Counterparty ineligible, wallet already verified, verification already in progress, or Sumsub prerequisites missing. Common `errorCode` values: `42012` (not self-hosted OWNED), `42021` (already verified), `42022` (in progress), `42014` (no Sumsub applicant), `42007` (application config not found).
- `500` — Unexpected server error.
- `503` — Sumsub temporarily unavailable

---

[API](https://skmtc.net/striga/apis/striga-v1.md) · [All operations](https://skmtc.net/striga/apis/striga-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/striga/striga-v1/revisions/63e57aa7df45/schema)