Business KYB process

Use the KYB process to verify a business account by creating a company account, initiating a KYB submission, and completing the company requirements returned by the API.

Core concepts

The KYB process uses the same submission-based flow as individual KYC.
The business account represents the company being verified.
The KYB submission returns the exact information, documents, and questionnaires required for that company.
The requirements array is the source of truth. Always submit the fields, documents, and questionnaire answers returned by the API.
After all requirements are fulfilled, complete the submission and wait for review.

KYB can include associated-party checks for shareholders, UBOs, directors, or authorised representatives. This guide documents the company-level KYB submission flow shown in the API response. Follow the requirements returned by the API for any additional associated-party requirements.

How parent and child applicants work in Sumsub KYB

In Sumsub KYB, the company is the main applicant. You can think of it as the parent applicant for the verification case.

People or entities connected to the company are associated parties under that parent applicant. These are commonly referred to as child applicants in the KYB review model. They can include:

Shareholders
Ultimate beneficial owners (UBOs)
Directors

The company-level applicant holds the business profile, registration details, corporate documents, and risk questionnaire. The child applicants hold the identity and screening information for the related parties, so flow is:

The company provides corporate information and documents.
Associated parties are identified from the ownership and control structure.
Relevant individuals go through identity verification and PEP/AML screening.
The reviewer evaluates the company, its documents, its risk profile, and its associated parties together.
The KYB case is approved, rejected, or sent back for additional information.

Expected flow

Create a business account.
Initiate the KYB process with POST /v1/kyc.
Read the submission requirements.
Provide company information.
Upload required company documents.
Submit the KYB questionnaire.
Add child applicants and link beneficiaries.
Complete the submission.
Wait for the KYB review result.

Prerequisites

Before you start:

Create or identify the company you want to onboard.
Collect the company’s registration information.
Collect the company documents listed in the KYB requirements.
Store your API key.

1. Create a business account

Create the Due account for the company.

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

Save the id from the response. This is the ACCOUNT_ID.

{
  "id": "acct_Dr3O86nqXLF86fGS"
}

Use this ID in the Due-Account-Id header for the rest of the KYB flow.

2. Initiate the KYB process

Start the KYB process with the same endpoint used for individual KYC.

curl --request POST \
     --url https://api.due.network/v1/kyc \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

The response returns an open KYB submission.

{
  "id": "ksub_i17QFoAT0jIwTU6a",
  "ownerId": "acct_Dr3O86nqXLF86fGS",
  "applicantId": "ka_TQQ0Px04oyVP1jIv",
  "status": "open",
  "info": {},
  "requirements": [
    {
      "kind": "static",
      "documents": [
        {
          "category": "COMPANY_DETAILS",
          "oneOf": [
            { "type": "INCORPORATION_CERT" },
            { "type": "GOOD_STANDING_CERT" }
          ]
        },
        {
          "category": "COMPANY_INCORPORATION",
          "oneOf": [
            { "type": "INCORPORATION_ARTICLES" }
          ]
        },
        {
          "category": "OWNERSHIP_STRUCTURE",
          "oneOf": [
            { "type": "SHAREHOLDER_REGISTRY" }
          ]
        },
        {
          "category": "CONTROL_STRUCTURE",
          "oneOf": [
            { "type": "DIRECTORS_REGISTRY" }
          ]
        },
        {
          "category": "PROOF_OF_ADDRESS",
          "oneOf": [
            { "type": "PROOF_OF_ADDRESS" }
          ]
        }
      ],
      "info": [
        { "key": "companyName", "type": "string" },
        { "key": "registrationNumber", "type": "string" },
        { "key": "registrationDate", "type": "date" },
        { "key": "taxId", "type": "string" },
        { "key": "phone", "type": "e164" },
        { "key": "address", "type": "object" },
        { "key": "website", "type": "website" }
      ],
      "questionnaires": [
        {
          "templateId": "kybQuestionnaireV1",
          "questions": []
        }
      ]
    }
  ],
  "documents": [],
  "questionnaires": [],
  "presetCode": "business",
  "source": "api"
}

Save the submission id. This is the SUBMISSION_ID.

ksub_i17QFoAT0jIwTU6a

3. Understand the KYB requirements

The KYB submission can include three requirement types:

Requirement	Description
`info`	Company data that must be submitted through the info endpoint.
`documents`	Company documents that must be uploaded.
`questionnaires`	KYB questionnaire answers that must be submitted.

In the example response, the submission requires:

Company information, including company name, registration number, registration date, tax ID, phone, address, and website.
Company documents, including incorporation, ownership, control, and proof-of-address documents.
Answers to the kybQuestionnaireV1 questionnaire.

4. Provide company information

Submit the company info fields returned in the requirements.

curl --request POST \
     --url https://api.due.network/v1/kyc/submissions/<SUBMISSION_ID>/info \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "companyName": "Example Company Ltd",
  "registrationNumber": "12345678",
  "registrationDate": "2020-01-15",
  "taxId": "GB123456789",
  "phone": "+442071234567",
  "website": "https://example.com",
  "address": {
    "country": "GB",
    "postCode": "SW1A 1AA",
    "town": "London",
    "street": "Downing Street",
    "buildingNumber": "10"
  }
}
'

The address object can include the fields returned in the requirements.

Field	Type
`country`	`iso3166_1_alpha2`
`postCode`	`swift_x`
`town`	`swift_x`
`street`	`swift_x`
`subStreet`	`swift_x`
`state`	`swift_x`
`stateCode`	`swift_x`
`buildingName`	`swift_x`
`flatNumber`	`swift_x`
`buildingNumber`	`swift_x`

Only include address fields that apply to the company.

5. Upload company documents

The documents array groups required documents by category. Each category includes a oneOf array listing acceptable document types.

For the example KYB submission, upload documents for each category below.

Category	Acceptable document type
`COMPANY_DETAILS`	`INCORPORATION_CERT` or `GOOD_STANDING_CERT`
`COMPANY_INCORPORATION`	`INCORPORATION_ARTICLES`
`OWNERSHIP_STRUCTURE`	`SHAREHOLDER_REGISTRY`
`CONTROL_STRUCTURE`	`DIRECTORS_REGISTRY`
`PROOF_OF_ADDRESS`	`PROOF_OF_ADDRESS`

Step 1: Request an upload token

Request an upload token for the document you want to upload.

curl --request POST \
     --url https://api.due.network/v1/kyc/submissions/<SUBMISSION_ID>/documents \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "INCORPORATION_CERT",
  "issuingCountry": "GB",
  "filename": "incorporation-certificate.pdf"
}
'

The response returns an upload token.

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Step 2: Upload the document

Use the token to upload the document file.

curl --request POST \
     --url https://api.due.network/v1/kyc/submissions/documents/<TOKEN> \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/pdf' \
     --data-binary '@path/to/incorporation-certificate.pdf'

Repeat this process for every required document category.

6. Submit KYB questionnaire answers

If the submission includes kybQuestionnaireV1, answer the questions returned in the requirements.

curl --request POST \
     --url https://api.due.network/v1/kyc/submissions/<SUBMISSION_ID>/questionnaires \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "templateId": "kybQuestionnaireV1",
  "answers": [
    {
      "id": "activity_description",
      "value": ["Example Company Ltd provides software services to business customers."]
    },
    {
      "id": "category",
      "value": ["business"]
    },
    {
      "id": "customer_types",
      "value": ["business"]
    },
    {
      "id": "customer_types_business",
      "value": ["Software and technology companies"]
    },
    {
      "id": "operation_countries",
      "value": ["GB"]
    },
    {
      "id": "prohibited_countries",
      "value": ["false"]
    },
    {
      "id": "due_usage",
      "value": ["expense", "payroll"]
    },
    {
      "id": "monthly_volume",
      "value": ["100k"]
    },
    {
      "id": "sof",
      "value": ["operating_assets"]
    },
    {
      "id": "sof_details",
      "value": ["Revenue from software subscriptions and professional services."]
    },
    {
      "id": "license_required",
      "value": ["false"]
    },
    {
      "id": "acknowledgement",
      "value": ["true"]
    }
  ]
}
'

Some questionnaire questions are conditional. Submit conditional answers only when the requirement applies.

Question ID	Required when
`category_other`	`category` is `na`
`customer_types_other`	`customer_types` includes `other`
`customer_types_business`	`customer_types` includes `business`
`prohibited_countries_text`	`prohibited_countries` is `true`
`due_usage_text`	`due_usage` includes `other`
`sof_text`	`sof` is `other`
`license_required_file`	`license_required` is `true`

7. Add child applicants and link beneficiaries

Use child applicants to represent people connected to the company, such as directors, shareholders or UBOs. After creating the child applicants, link them back to the company submission as beneficiaries.

Step 1: Create a child applicant

Create a child applicant under the KYB submission and submit the info for it.

curl --request POST \
     --url https://api.sandbox.due.network/v1/kyc/submissions/<SUBMISSION_ID>/applicants \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "individual",
  "roles": ["director"]
}
'

The response returns the updated submission. Save the child applicant ID from the response. You use this value as applicantId when linking the beneficiary.

ka_child_123

Create one child applicant for each related person required by the KYB case.

Field	Type	Description
`type`	string	Applicant type. Use `individual` for a related person.
`roles`	array of strings	The person’s role in relation to the company, such as `director`, `shareholder`, `ubo`. Use the roles required for your KYB case.

Step 2: Link beneficiaries to the company submission

After creating child applicants and executing their submissions, link them to the company submission with the relations endpoint.

curl --request POST \
     --url https://api.sandbox.due.network/v1/kyc/submissions/<SUBMISSION_ID>/relations \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "applicantId": "ka_child_123",
    "roles": ["director"],
    "shareSize": "25"
  }
]
'

The request body is an array, so you can link multiple beneficiaries in one request.

[
  {
    "applicantId": "ka_child_123",
    "roles": ["director"],
    "shareSize": "25"
  },
  {
    "applicantId": "ka_child_456",
    "roles": ["ubo", "shareholder"],
    "shareSize": "50"
  }
]

Field	Type	Description
`applicantId`	string	Child applicant ID returned when you created the child applicant.
`roles`	array of strings	The beneficiary’s role or roles in the company.
`shareSize`	string	Ownership share for the beneficiary, when applicable. Use the value required for the KYB case.

After linking beneficiaries, fetch the submission again and inspect the updated requirements. If the response returns additional information, document, or questionnaire requirements for the associated parties, complete those requirements before submitting the KYB case.

curl --request GET \
     --url https://api.sandbox.due.network/v1/kyc/submissions/<SUBMISSION_ID> \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

8. Complete the submission

After all requirements are fulfilled, complete the submission.

curl --request POST \
     --url https://api.sandbox.due.network/v1/kyc/submissions/<SUBMISSION_ID>/complete \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

After review and approval, Due sends a webhook with the account KYC status.

{
  "type": "bp.kyc.status_changed",
  "data": {
    "id": "<ACCOUNT_ID>",
    "kyc": {
      "status": "passed"
    }
  }
}

Troubleshooting

The submission cannot be found

Check that you are using the same Due-Account-Id that initiated the KYB process.

Due-Account-Id: <ACCOUNT_ID>

The submission still shows open requirements

Fetch the submission and inspect the requirements, documents, and questionnaires arrays. The API response is the source of truth for what remains missing.

A document upload is rejected

Check that the type matches one of the document types in the relevant oneOf array and that the uploaded file content type matches the file you are sending.