Sumsub Developer Hub

# Know Your Business

# Introduction

With Sum&Substance you can easily verify your business clients and their beneficiaries. To see the list of documents that we use for KYB checks, click here.

# Business Verification API

All API requests must be authenticated as described in this section.

You should use separate applicants for each entity (individuals and companies) otherwise the check and ongoing monitoring will be inconsistent.

# Creating a company applicant

By a company applicant we mean a company that needs to be verified.

POST /resources/applicants?levelName={levelName}

Applicant level should contain Company verification step.

# REQUEST ARGUMENTS
Name Type Required Description
levelName String Yes Name of user verification steps configuration that you should set up at the dashboard
#{body} Object Yes An object representing an applicant (see example).
# REQUEST BODY
Name Type Required Description
externalUserId String Yes An applicant ID on the client side. Should be unique.
sourceKey String No Provide this field if you need to distinguish between the clients from which you receive applicants.
email String No Applicant's email.
lang String No The language in which the applicant should see the verification result.
metadata Array of strings No Additional information that is not displayed to the end user ( Example: [{"key": "keyFromClient", "value": "valueFromClient"}] ).
info Object Yes Basic information about the applicant.
type String Yes Type of applicant (company, individual).
# info.companyInfo ATTRIBUTE
Name Type Required Description
companyName String Yes Name of the company.
registrationNumber String Yes Registration number.
country String Yes A three-letter country code (e.g. DEU or RUS) (Wikipedia).
legalAddress String No Legal name.
incorporatedOn String No Date of incorporation (format YYYY-mm-dd, e.g. 2001-09-25).
type String No Type of entity.
email String No Email address.
controlScheme String No Description of the control scheme of the group of entities.
phone String No Phone number.
taxId String No Taxpayer registration number/Code of taxpayer registration.
registrationLocation String No Location of registration.
website String No Website's URL.
postalAddress String No Postal address.
beneficiaries Array No Contains applicantIds of beneficiaries and additional info like position and type.
addresses Array No List of addresses.
# Example request
# Example response

# Adding an existing individual applicant as a beneficiary

This method is used to add an existing individual applicant as a beneficiary of the company applicant.

If you need information on how to create an individual applicant, please refer to the Creating an applicant section.

POST /resources/applicants/{applicantId}/info/companyInfo/beneficiaries?sendEmail=false

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Company applicant ID
sendEmail Boolean No Sends a verification email to the added beneficiary if set to true
body Object Yes Beneficiary info
# REQUEST BODY
Name Type Required Description
applicant Object Yes Object representing individual applicant's identifier
applicantId String Yes Applicant Id of beneficiary
positions Array No The list of positions in the company (["director","shareholder","other"])
type String Yes Type of beneficiary: ubo or shareholder or representative
# Example request
# Example response

# Removing applicant from the list of beneficiaries

Removes applicant from the list of company beneficial owners.

DELETE /resources/applicants/{applicantId}/info/companyInfo/beneficiaries/{beneficiaryApplicantId}

Name Type Required Description
applicantId String Yes Company applicant ID
beneficiaryApplicantId String Yes Beneficiary applicant ID
# Example request
# Example response

# Adding a company document

This method uses a multipart/form-data POST request that contains COMPANY doc JSON metadata and a document photo/scan.

Please note that documents of individuals like beneficiary's identity documents should not be sent to company applicant for consistency of the check.

POST /resources/applicants/{applicantId}/info/idDoc

# REQUEST HEADERS
Name Type Value
Content-Type String multipart/form-data
# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID
# FORM DATA
Name Type Required Description
metadata Object Yes An object representing an ID document
content Binary No A photo of a document
# REQUEST metadata BODY PART FIELDS
Name Type Required Description
idDocType String Yes Document type.
idDocSubType String No See supported idDocSubTypes for COMPANY_DOC below.
country String Yes A three-letter country code (Wikipedia).
# Supported idDocTypes for company verification:
Value Description
COMPANY_DOC Default type of the document for company verification.
TRANSPARENCY_REGISTRY_EXTRACT Recent excerpt from a transparency company registry.
POWER_OF_ATTORNEY Power of attorney.
# Supported idDocSubTypes for COMPANY_DOC:
Value Description
DIRECTORS_REGISTRY Directors registry.
STATE_REGISTRY Recent excerpt from a state company registry.
INCUMBENCY_CERT Certificate of incumbency.
PROOF_OF_ADDRESS Proof of address. For example, a utility bill, rent contract or an electricity bill.
TRUST_AGREEMENT Trust agreement.
PROOF_OF_DOMAIN Proof of domain.
INFORMATION_STATEMENT Statement of information.
INCORPORATION_CERT Certificate of incorporation/registration.
INCORPORATION_ARTICLES Memorandum/articles of incorporation/association/registration.
SHAREHOLDER_REGISTRY Shareholder registry.
GOOD_STANDING_CERT Certificate of good standing.
# RESPONSE

JSON representing added document information.

If you need to know the imageId of the photo, you can find it in this information in the response header X-Image-Id

# Example request
# Example response

# Requesting an applicant check

That request is used to programmatically ask us to check an applicant when needed.

POST /resources/applicants/{applicantId}/status/pending

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID
# RESPONSE

If you receive a 200 response, you may ignore the response body.

# Example request
# Example response

# Getting company data

GET /resources/applicants/{applicantId}/one

or

GET /resources/applicants/-;externalUserId={externalUserId}/one

You may want to use the second request when you don't know an applicant id yet. E.g. when WebSDK created an applicant for you and we called your webhook endpoint.

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant id
externalUserId String Yes User id in your system
# RESPONSE

It's basically an applicant that you've created (or we've created for you, e.g. via WebSDK) with augmented information in cases where a verification has been completed. The info.companyInfo structure contains information about company and its beneficiaries.

Description of companyInfo attributes you can find here.

# Example request
# Example response

# Changing company data

If you want to change a company data you can call a PATCH request instead of creating a new applicant, which is highly discouraged. This method patches the fields in the info key of the applicant.

PATCH /resources/applicants/{applicantId}/info/companyInfo

# REQUEST ARGUMENTS

The body of companyInfo must contain all those fields that have value. Null fields at info.companyInfo will be unset. So it's better to get previously filled data first with this method.

Name Type Required Description
#{body} Object No Field in the info.companyInfo attribute that should be changed
applicantId String Yes Applicant ID
# RESPONSE

A patched info entity. As this endpoint could be quite damaging if misused, please check that it returns expected results on the sandbox environment.

# Example request
# Example response

# Getting company applicant status

GET /resources/applicants/{applicantId}/requiredIdDocsStatus

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant ID
# RESPONSE

A breakdown for each step. Each step contains an array of images' IDs.

# Example request:
# Example response:

# Getting additional company check data

Using this method you can fetch a company check result data after the applicant being reviewed.

GET /resources/checks/latest?type=COMPANY&applicantId={applicantId}

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Applicant id
# RESPONSE

Response represents a singleton list of checks with info on the company. All attributes below are nullable.

Name Type Description
answer String Company check answer (GREEN/RED/YELLOW)
createdAt Date Time and date of the latest company check result
companyCheckInfo Object Company check data
# companyCheckInfo ATTRIBUTES
Name Type Description
companyName String Company name
companyNumber String Company registry number
status String Company status
type String Company type
source String Company data source/registry
sourceUrl String Source URL
webPage String Company web page address
officeAddress String Company office address
incorporatedOn Date Date of incorporation
industryCodes List of Objects List of industry codes and descriptions
alternativeNames List of Strings List of alternative company names
licenseInfo Object Company license info
officers List of Objects List of company officers
significantPersons List of Objects List of significant company persons
affiliatedCompanies List of Objects List of affiliated companies - has the same attributes as companyCheckInfo
# industryCodes ELEMENT ATTRIBUTES
Name Type Description
code String Company industry code
description String Industry description
# licenseInfo ATTRIBUTES
Name Type Description
licenseNumber String License number
issuedDate Date Date of issue
validUntil Date Date of expiry
# officers and significantPersons ELEMENT ATTRIBUTES
Name Type Description
fullName String Full name
dob Date Date of birth
nationality String Nationality
country String Country of residence
occupation String Occupation
appointedOn Date Date of person being appointed
correspondenceAddress String Correspondence address
natureOfControl String Nature of control
role String Role
status String Status
# Example request
# Example response
Last Updated: 1/17/2023, 2:32:35 PM