Sumsub

Overview

The Sumsub blueprint crawls KYC verification data from Sumsub, including applicants, document checks, screening hits, and review decisions, and exposes enrichment lookups and remediation actions so callers can read and write applicant state on demand.

Configurations

Configuration	Description
Blueprint Account Name	Human-readable identifier for this Sumsub account in the platform.
App Token	Sumsub App Token used for API authentication.
Secret Key	Sumsub Secret Key used to sign API requests.
Data Crawl Frequency	How often Kscope pulls updated applicant, document, and review data from Sumsub.

Permissions

API credentials are created in the Sumsub dashboard under Dev Space → App Tokens. Both an App Token and its matching Secret Key are required.

Read scope covers applicant, status, and AML case endpoints. Remediation additionally requires write scope on applicant tags. Grant the token the built-in Applicants — read and Applicants — write permissions if you plan to use remediation actions.

For step-by-step token creation, see the Sumsub API authentication guide.

Enrichment Lookups

The Sumsub blueprint supports on-demand enrichment lookups so AI agents and downstream automations can fetch live applicant state without waiting for the next crawl.

Lookup Type	Description	Parameters
applicant.get	Retrieve the full applicant record including identity, documents, and review metadata	applicantId (required)
applicant.status	Retrieve the current review status and decision for an applicant	applicantId (required)
applicant.amlCase	Retrieve the AML case (sanctions/PEP/adverse-media hits) for an applicant. Returns empty results when no AML case has been generated (for example, when the applicant's verification level has no AML screening configured).	applicantId (required)

Lookups reuse the same appToken and secretKey credentials configured for the crawl.

Remediation Actions

The Sumsub blueprint supports write-back remediation actions so AI agents and compliance workflows can annotate applicants with FinCrime state directly from Kscope.

Action	Description	Arguments
applicant.tags.add	Attach disposition tags to an existing applicant (e.g. needs-review, cleared, escalated-to-SAR). Tags are visible in the Sumsub dashboard and carried on subsequent applicant fetches.	applicantId (required), tags (required list)
applicant.create	Create a new applicant in Sumsub with the supplied identity payload. If tags are supplied alongside, they are written to the newly-created applicant in the same call.	levelName, externalUserId, firstName, lastName (required); middleName, dob, country, nationality, email, phone, addressJSON, tags (optional)

applicant.create inputs

Field	Description
levelName	Sumsub verification level to apply (tenant-configured in the Sumsub dashboard, e.g. basic-kyc-level, id-only).
externalUserId	External identifier stamped on the new applicant for correlation back to the caller's own system.
firstName, lastName, middleName	Applicant name.
dob	Date of birth (YYYY-MM-DD).
country, nationality	ISO-3 country codes.
email, phone	Optional contact fields (phone in E.164 format).
addressJSON	JSON array of Sumsub address objects (fields: country, town, street, postCode, etc.).
tags	Optional list of tags applied to the new applicant.

Sumsub does not auto-run AML screening on applicants created via the API; the new record lands in reviewStatus=init and waits for documents or a manual status transition.

Remediations honour dryRun; a dry-run returns the intended action without writing to Sumsub.

Note: dashboard-style case creation (notes, evidence uploads, case-level state) requires Sumsub Case Management v2, which is enabled per-account on request. Until CM v2 is activated on your tenant, applicant.create + applicant.tags.add are the supported remediation surface.

Schema Model

Resource	Source Entity	Normalized Entity	Description
Sumsub Applicant	sumsub.applicant.Applicant	Applicant	A Sumsub applicant record, including identity fields and review status.
Document Check	sumsub.applicant.DocumentCheck	DocumentCheck	The result of verifying a submitted identity document.
Screening Hit	sumsub.applicant.ScreeningHit	ScreeningHit	A match produced by Sumsub's screening against sanctions, PEP, and watchlists.