Add a KYC check to a transaction workflow

POST/transaction-workflows/{id}/actions/add-kyc

transaction-workflows:write add_kyc_transaction_workflow

Adds the app's two protected kyc steps and returns the workflow. "Complete KYC Checks (label)" moves an investor on to "KYC Completed (label)" once their Sumsub check at the given levels passes; the completed step requires a valid KYC record. They go at the end of the chain, or between after_step_ids and before_step_ids, moving later steps up. Unknown levels or steps return 422, steps that don't link that way 409. It emits no webhook; remove-kyc undoes it.

Path parameters

idstring (uuid)Required#
The record's id.

Query parameters

dry_runboolean#
Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

Idempotency-Keystring#
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required

labelstringRequired#
Names the two steps, in brackets after their titles.
sumsub_kyc_level_idstring (uuid)Required#
The Sumsub check level for individuals, from GET /kyc/levels.
sumsub_kyb_level_idstring | null#
The Sumsub check level for companies, if any.
after_step_idsstring (uuid)[]#
The steps the KYC check step follows.
before_step_idsstring (uuid)[]#
The steps the KYC completed step leads to.

{
  "label": "Standard",
  "sumsub_kyc_level_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d"
}

Responses

200

The workflow, with its new KYC steps.

TransactionWorkflow

{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "name": "string",
    "label": "string",
    "description": "string",
    "status": "draft",
    "is_default": true,
    "kyc_check_step_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "steps": [
      {
        "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
        "workflow_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
        "name": "string",
        "label": "string",
        "type": "string",
        "kind": "linear",
        "description": "string",
        "is_protected": true,
        "is_floating": true,
        "order": 1,
        "has_custom_form": true,
        "is_internal_only": true,
        "show_default_internal_message": true,
        "document_upload": {},
        "minimum_investment": {},
        "document_release": {},
        "webhook": {},
        "posts_to_portfolio": true,
        "info_banner": {},
        "requirements": [],
        "triggers": [],
        "created_at": "2026-06-12T10:00:00+00:00",
        "updated_at": "2026-06-12T10:00:00+00:00"
      }
    ],
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00"
  }
}

401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error

403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error

404

Resource not found (error.code = not_found).

Error

409

The request conflicts with existing state (error.code = conflict), e.g. a compliance flow with the requested name already exists.

Error

422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/transaction-workflows/{id}/actions/add-kyc\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "label": "Standard",
  "sumsub_kyc_level_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d"
}'