Sumsub KYB Sharing

Use Sumsub KYB sharing to import verified business applicant data from another Sumsub-integrated platform, then complete any company or related-person requirements through Due submissions.

Overview

Sumsub KYB sharing uses the same sharing endpoint as KYC sharing:

POST /v1/kyc/sharing/sumsub

The main difference is the applicant model. In KYB, the company is the primary applicant, and related individuals are represented as child applicants linked to that company.

This means a KYB sharing flow can involve:

• A business account representing the company.
• A parent applicant representing the company KYB applicant.
• One or more child applicants representing related individuals, such as directors, representatives, or beneficial owners.
• A submission that contains company requirements, child applicant requirements, relationship requirements, or a combination of these.

Expected flow

1. Create the business account for the company.
2. Get a Sumsub share token for the company applicant.
3. Call POST /v1/kyc/sharing/sumsub for the business account.
4. Check whether the response returns completed or resubmission_pending.
5. If a submission is pending, inspect the submission requirements.
6. Provide missing company information, documents, or questionnaires.
7. Create child applicants when the KYB submission requires related individuals.
8. Set relationships between the company applicant and child applicants.
9. Complete the submission.
10. Wait for the final KYB decision webhook before enabling KYB-gated services.

Sharing imports data from Sumsub. It does not guarantee KYB approval. Due still evaluates the KYB submission and returns the final decision through webhook events.

Prerequisites

Before you start:

1. Create a business account for the company.
2. Get a Sumsub share token from the platform where the company completed KYB.
3. Store the business account ID. You use it in the Due-Account-Id header.
4. Prepare to complete any missing company or related-person requirements through the submission API or the hosted flow.

1. Create the business account

Create the Due account for the company before calling the sharing endpoint.

curl --request POST \
  --url https://api.due.network/v1/accounts \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "business",
    "name": "Example Company Ltd",
    "email": "[email protected]",
    "country": "GB",
    "category": "company"
  }'

Save the returned account ID. Use it as Due-Account-Id for the rest of the KYB sharing flow.

{
  "id": "acct_company_123",
  "type": "business",
  "name": "Example Company Ltd"
}

2. Share the Sumsub KYB applicant

Call the Sumsub sharing endpoint with the business account ID in Due-Account-Id.

curl --request POST \
  --url https://api.due.network/v1/kyc/sharing/sumsub \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "shareToken": "st_abc123...",
    "applicantInfo": {
      "companyName": "Example Company Ltd",
      "registrationNumber": "12345678",
      "phone": "+442071234567"
    },
    "questionnaire": {
      "templateId": "kybQuestionnaireV1",
      "answers": []
    }
  }'

The request body follows the same structure as KYC sharing:

3. Read the sharing response

The sharing response returns a submission ID and a status.

{
  "status": "resubmission_pending",
  "submissionId": "ksub_company_123"
}

4. Fetch the KYB submission

When the response status is resubmission_pending, fetch the submission by ID.

curl --request GET \
  --url https://api.due.network/v1/kyc/submissions/ksub_company_123 \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123'

The submission shows what is missing.

{
  "id": "ksub_company_123",
  "ownerId": "acct_company_123",
  "applicantId": "acct_company_123",
  "status": "open",
  "info": {},
  "requirements": [
    {
      "kind": "static",
      "info": [
        { "key": "companyName", "type": "string" },
        { "key": "registrationNumber", "type": "string" },
        { "key": "address", "type": "object" }
      ]
    }
  ],
  "documents": [],
  "questionnaires": []
}

Use the same business account ID in Due-Account-Id when fetching or completing the KYB submission. If you use a different account ID, the submission may not be found.

KYB applicant model: parent and child applicants

In KYB, the company is the parent applicant. Related individuals are child applicants.

The parent applicant represents the business account and its company-level verification requirements. Child applicants represent people associated with the company, such as directors, representatives, or beneficial owners.

Use child applicants when the KYB submission requires information about individuals connected to the company.

5. Provide missing company information

If the submission requires company info fields, provide them through the submission info endpoint.

curl --request POST \
  --url https://api.due.network/v1/kyc/submissions/ksub_company_123/info \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "companyName": "Example Company Ltd",
    "registrationNumber": "12345678",
    "entityType": "company",
    "phone": "+442071234567",
    "website": "https://example.com",
    "address": {
      "country": "GB",
      "postCode": "SW1A 1AA",
      "town": "London",
      "street": "Downing Street"
    }
  }'

Only submit fields required by the submission requirements or fields you are intentionally pre-filling for review.

6. Add company documents when required

If the KYB submission requires company documents, request an upload token.

curl --request POST \
  --url https://api.due.network/v1/kyc/submissions/ksub_company_123/documents \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "COMPANY_REGISTRATION_DOCUMENT",
    "issuingCountry": "GB",
    "filename": "company-registration.pdf"
  }'

Then upload the file using the returned token.

curl --request POST \
  --url https://api.due.network/v1/kyc/submissions/documents/<UPLOAD_TOKEN> \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123' \
  --header 'Content-Type: application/pdf' \
  --data-binary '@company-registration.pdf'

Use the document types returned in the submission requirements. Do not assume a fixed KYB document list.

10. Add questionnaire answers

If the submission requires questionnaires, submit the answers using the questionnaire endpoint.

curl --request POST \
  --url https://api.due.network/v1/kyc/submissions/ksub_company_123/questionnaires \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "kybQuestionnaireV1",
    "answers": []
  }'

Use the templateId and question IDs returned in the submission requirements.

11. Complete the KYB submission

After all company, child applicant, document, relationship, and questionnaire requirements are satisfied, complete the submission.

curl --request POST \
  --url https://api.due.network/v1/kyc/submissions/ksub_company_123/complete \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_company_123'

After completion, wait for the KYB review result before enabling services that require KYB approval.

Optional: Use the hosted submission flow

You can send the user through Due’s hosted submission flow instead of collecting all missing data through your own API integration.

Create a session for the pending submission.

curl --request POST \
  --url https://api.due.network/v1/kyc/sessions \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "submissionId": "ksub_company_123"
  }'

Use the returned token or hosted flow details to let the company representative complete the missing KYB information.

Webhook events

Listen for KYC/KYB webhook events to track submission creation and final review decisions.

When sharing creates a pending submission, Due sends a submission-created event. The event includes the submission ID and requirements.

When KYB review finishes, Due sends the final status change event for the account.

Errors and fallback

The Sumsub sharing endpoint can fail or return a pending submission.

Handle these cases explicitly:

Summary

Sumsub KYB sharing follows the same sharing and submission endpoints as KYC sharing, but the KYB applicant model is different.

For KYB:

1. Create the business account first.
2. Share the company Sumsub applicant with POST /v1/kyc/sharing/sumsub.
3. Treat the company as the parent applicant.
4. Create child applicants for related individuals when required.
5. Set relationships between the company and child applicants.
6. Complete all remaining submission requirements.
7. Wait for the final KYB decision before enabling KYB-gated services.