Skip to main content

Sumsub Integration

If you use Sumsub for identity verification, you can share the verified applicant data directly with Monerium using the KYC Sharing flow for personal profiles, or the KYB Sharing flow for corporate profiles when Monerium has enabled corporate sharing for your partner. Sharing automates the retrieval of verified customer details and documents, accelerating your onboarding.

Sandbox preview

KYB Sharing is available in sandbox, not yet released to production — see Corporate profiles.

To share applicant data, you must first configure Monerium as a recipient partner in your Sumsub dashboard.


1. Configure Monerium as a Recipient​

To enable KYC sharing, you need to add Monerium as a partner using our share token:

  1. Log in to your Sumsub Dashboard.
  2. From the left sidebar, navigate to Reusable Identity ➔ Partners ➔ Recipients.
  3. Click on Add Recipient.
  4. Enter your Monerium-provided partner share token.
Monerium client ID

Our Sumsub client ID is monerium.com. If you generate share tokens yourself via the Sumsub API, pass this value in the forClientId field.


2. Set Up a Verification Level​

Monerium imports the data and documents your levels collect. Configure the levels below so that the shared applicant carries everything Monerium needs; incomplete data delays the import or leaves the profile incomplete.

Personal profiles​

Partners must configure a Sumsub verification level that requires all three of the following:

  1. ID document
  2. Selfie for liveness check
  3. Proof of address

Applicants that do not complete all three checks will fail Monerium's pre-checks.

See document acceptance by issuing country for document requirements.

Corporate profiles​

Sandbox preview

KYB Sharing is available in sandbox, not yet released to production. Everything below is subject to change before release, and Monerium must enable corporate sharing for your partner.

Corporate sharing uses one company level plus two individual levels for the company's associated parties. Monerium must enable corporate sharing for your partner before you can share a corporate applicant.

Monerium's sandbox tenant uses the levels below as a reference. Create equivalents in your own account.

Set up the levels in the Sumsub dashboard​

All three levels are created in the Sumsub dashboard:

  • Company level: Configurations ➔ Applicant verification ➔ Company levels ➔ Create level. Add the Company Data, Company documents, and Associated parties steps described below. See Sumsub's Business Verification guide for the full level builder.
  • Individual levels: Configurations ➔ Applicant verification ➔ Individual levels ➔ Create level (type Standard). See Sumsub's verification level guide.

In the company level's Associated parties step, add one role per category below, select With verification level, and pick the mapped level under Select verification level. Use Set limits on the representatives role to cap it at one applicant — Monerium currently supports a single representative per company, and a shared applicant with more than one fails the import.

Level settings

A level's name cannot be changed after it is saved, and level configuration is shared between the Sumsub sandbox and production.

Company level​

The company level collects the company data and documents Monerium stores on the corporate profile.

Company data (all required):

FieldNotes
companyNamePrefilled from the registry (companyInfo.companyName)
registrationNumberPrefilled from the registry (companyInfo.registrationNumber)
incorporationDateRegistration date in YYYY-MM-DD format (companyInfo.incorporatedOn or applicant registrationDate)
countryPrefilled from the registry (companyInfo.country)
streetRegistered street address (companyInfo address)
postCodePostal code
townCity
stateState or county
emailCompany email address (companyInfo.email or applicant top-level email)
phoneCompany phone number, in E.164 format including the country code (companyInfo.phone or applicant top-level phone)

The company email, phone, and incorporation date are mandatory: corporate profiles stay incomplete and are not submitted for review until they are present. Missing registry data (name, registration number, country, address) is gap-filled from the registry-backed company check, but the contact fields and registration date must be present on the applicant.

Company documents (all required):

GroupDocument types
legalPresenceIncorporation certificate (INCORPORATION_CERT) or state registry extract (STATE_REGISTRY)
companyDetailsProof of address (PROOF_OF_ADDRESS)
ownershipStructureShareholder registry (SHAREHOLDER_REGISTRY)
representativesAuthorizationPower of attorney (POWER_OF_ATTORNEY) or incorporation certificate (INCORPORATION_CERT)
controlStructureDirectors registry (DIRECTORS_REGISTRY) or incumbency certificate (INCUMBENCY_CERT)

Associated parties. Set the UBO and shareholder thresholds to 25% and map each category to an individual level:

CategoryIndividual levelExtra fields
representativesRepresentative level—
ubosAssociated-person levelshareSize
directorsAssociated-person level—

Every associated applicant must carry the following fields; Monerium imports them into the person record, and a person missing any of them is not imported:

firstName, lastName, dob, email, phone, nationality, country, street, town, state, postCode

Beneficial owners additionally provide shareSize, their ownership percentage. Collect the fields on each role in the Associated parties step; Monerium also reads matching fields from the individual applicant when present.

Representative level​

The representative (authorised signatory) goes through a full individual level:

StepRequirement
IDENTITYID card, passport, or residence permit
SELFIESelfie with passive liveness
PROOF_OF_RESIDENCEUtility bill, bank or credit card statement, or government-issued document (tax statement, certificate of residency, government letter)

Associated-person level​

Directors and beneficial owners use a lighter individual level:

StepRequirement
IDENTITYID card, passport, or residence permit
PROOF_OF_RESIDENCEUtility bill, bank or credit card statement, or government-issued document (tax statement, certificate of residency, government letter)

No selfie is required for this level. Both individual levels accept the proof-of-address documents listed above; the document must show the person's name and current address.

Map the categories in the company level to the individual levels: representatives to the representative level, and UBOs and directors to the associated-person level. Monerium records the level each associated applicant was verified under; a mismatch is imported but the person is queued for manual review instead of being approved automatically.

Shareholder role

Do not configure a separate required shareholder role. At a 25% UBO threshold, every individual shareholder at or above 25% is already declared as a UBO, and Monerium does not model shareholders below that threshold. Requiring it can block companies owned by other entities or without an individual shareholder at 25% or more.

Sumsub webhooks

Configure the Sumsub webhook for both company and individual applicants. Monerium consumes the company applicant webhook and fetches the linked individual applicants itself; individual-level webhooks are not required for corporate ingestion.


3. Sandbox Testing with Sumsub Templates​

When testing your integration in the sandbox environment, we highly recommend creating test applicants in Sumsub using Sumsub's official document templates.

In particular, German document templates work exceptionally well for verification and simulate a real user onboarding experience successfully.

  • Refer to the Sumsub Verification Document Templates guide to download sample documents (such as IDs, Passports, and Proof of Address).
  • Upload these template documents when creating test applicants in your Sumsub sandbox dashboard to easily trigger successful verifications.

4. Sharing Applicant Data via API​

Once Monerium is configured as a recipient partner, you can share applicant details via the API using the /profiles/{profileId}/share endpoint.

Personal profiles​

await fetch(`https://api.monerium.dev/profiles/${profileId}/share`, {
method: 'POST',
headers: {
Authorization: `Bearer ${access_token}`,
'Content-Type': 'application/json',
Accept: 'application/vnd.monerium.api-v2+json',
},
body: JSON.stringify({
provider: 'sumsub',
personal: { token: sumsubApplicantToken },
}),
});

Corporate profiles​

await fetch(`https://api.monerium.dev/profiles/${profileId}/share`, {
method: 'POST',
headers: {
Authorization: `Bearer ${access_token}`,
'Content-Type': 'application/json',
Accept: 'application/vnd.monerium.api-v2+json',
},
body: JSON.stringify({
provider: 'sumsub',
corporate: { token: sumsubApplicantToken },
}),
});

Both requests return 202 Accepted. Monerium fetches the applicant asynchronously; wait for a profile.updated webhook before reading the imported data. Sumsub does not provide the corporate form data (service, legal form, purpose, activity, fund origin, monthly turnover, and transaction count). Submit that separately via PATCH /profiles/{profileId}/form.

For a full step-by-step walkthrough of the Whitelabel onboarding flow and how to call this endpoint, please see the Whitelabel Onboarding Guide. For the corporate data contract, see the KYB Guide.