Sumsub Developer Hub

# Know Your Business

# Introduction

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

# 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 results of the check and ongoing monitoring will be inconsistent.

# Creating a company applicant

By 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

Required attributes are needed to properly verify company data during check. That info is not necessarily to be added on creation but make sure to provide before the check is requested.

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

# REQUEST ARGUMENTS
Name Type Required Description
applicantId String Yes Company applicant ID.
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 check results consistency.

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.
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.
OTHER Subtype for a document when none of above subtypes apply.
# 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

By requesting a check, we can programmatically check an applicant for you 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.

You can find description of companyInfo attributes 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 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

By using this method, you can get a company check result data after the applicant has been 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: 9/1/2023, 7:01:06 AM