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

# 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 on test and production environments.
#{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 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.
# 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 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

But you can 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.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: 10/18/2020, 4:01:34 PM