# 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

# Creating a company applicant

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

POST /resources/applicants

The request body should contain the requiredIdDocs parameter and there should be only one idDocSetType in docSets, namely COMPANY.

# REQUEST ARGUMENTS
Name Type Required Description
#{body} Object Yes An object representing a company applicant (see example below).
# 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"}] ).
requiredIdDocs Object Yes Description of the required document set.
info Object Yes Basic information about the applicant.
type String No 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 addicional info like position and type.
addresses Array No List of addresses.
# ATTRIBUTES FOR steps OF idDocSetType: COMPANY.
Name Type Required Description
name String Yes Name of step: company,ubos,shareholders,representatives.
minDocsCnt Integer No Minimum number of required documents.
idDocType String No See supported company documents below.
idDocSubType String No See supported idDocSubTypes for COMPANY_DOC here.
# Supported idDocSubTypes for COMPANY verification step
Value Description
COMPANY_DOC Document confirming legal existence of the company.
TRANSPARENCY_REGISTRY_EXTRACT Recent excerpt from a transparency registry.
POWER_OF_ATTORNEY Power of attorney.
# 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 Yes 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
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

# Adding a company document

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

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 See supported company document types here.
idDocSubType String No See supported idDocSubTypes for COMPANY_DOC below.
country String Yes A three-letter country code (Wikipedia).
# 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

An applicant gets the pending status automatically once all the documents specified in requiredIdDocs are uploaded. But you can programmatically ask us to check an applicant if 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}

or

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

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.idDocs.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

# 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 test environment.

Changing applicant data will cause the applicant to be switched back to the pending state.

# 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:
Last Updated: 6/9/2020, 2:41:14 PM