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.
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:
- Log in to your Sumsub Dashboard.
- From the left sidebar, navigate to Reusable Identity ➔ Partners ➔ Recipients.
- Click on Add Recipient.
- Enter your Monerium-provided partner share token.
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:
- ID document
- Selfie for liveness check
- 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
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.
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):
| Field | Notes |
|---|---|
companyName | Prefilled from the registry (companyInfo.companyName) |
registrationNumber | Prefilled from the registry (companyInfo.registrationNumber) |
incorporationDate | Registration date in YYYY-MM-DD format (companyInfo.incorporatedOn or applicant registrationDate) |
country | Prefilled from the registry (companyInfo.country) |
street | Registered street address (companyInfo address) |
postCode | Postal code |
town | City |
state | State or county |
email | Company email address (companyInfo.email or applicant top-level email) |
phone | Company 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):
| Group | Document types |
|---|---|
legalPresence | Incorporation certificate (INCORPORATION_CERT) or state registry extract (STATE_REGISTRY) |
companyDetails | Proof of address (PROOF_OF_ADDRESS) |
ownershipStructure | Shareholder registry (SHAREHOLDER_REGISTRY) |
representativesAuthorization | Power of attorney (POWER_OF_ATTORNEY) or incorporation certificate (INCORPORATION_CERT) |
controlStructure | Directors 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:
| Category | Individual level | Extra fields |
|---|---|---|
representatives | Representative level | — |
ubos | Associated-person level | shareSize |
directors | Associated-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:
| Step | Requirement |
|---|---|
IDENTITY | ID card, passport, or residence permit |
SELFIE | Selfie with passive liveness |
PROOF_OF_RESIDENCE | Utility 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:
| Step | Requirement |
|---|---|
IDENTITY | ID card, passport, or residence permit |
PROOF_OF_RESIDENCE | Utility 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.
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.
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.