# 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. |
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. |
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
curl -X POST \
'https://api.sumsub.com/resources/applicants?levelName=kyb-level' \
-H 'Content-Type: application/json' \
-d '{
"externalUserId": "someClientUserIdCompany",
"info": {
"companyInfo": {
"companyName": "COMPANY NAME LTD",
"registrationNumber" : "09688671",
"country" : "GBR",
"incorporatedOn" : "2015-01-01",
"type" : "Private Company Limited by Shares",
"email" : "[email protected]",
"phone" : "+12366020172",
"website" : "sumsub.com"
}
},
"type": "company"
}'
# Example response
{
"id": "5e9412223cc1813b4db0b0e3",
"createdAt": "2020-10-10 00:05:20",
"clientId": "rda_t_key",
"inspectionId": "5e9412223cc1813b4db0b0e4",
"externalUserId": "someClientUserIdCompany",
"info": {
"companyInfo": {
"companyName": "COMPANY NAME LTD",
"registrationNumber": "09688671",
"country": "GBR",
"incorporatedOn": "2015-01-01 00:00:00",
"type": "Private Company Limited by Shares",
"email": "[email protected]",
"phone": "+12366020172",
"website": "sumsub.com"
}
},
"requiredIdDocs": {
"docSets": [
{
"idDocSetType": "COMPANY",
"types": [
"COMPANY_DOC"
],
"steps": [
{
"name": "company",
"minDocsCnt": 1,
"idDocTypes": [
"COMPANY_DOC"
],
"idDocSubTypes": null,
"fields": null,
"customFields": null
},
{
"name": "ubos",
"minDocsCnt": null,
"idDocTypes": null,
"idDocSubTypes": null,
"fields": null,
"customFields": null
}
]
}
]
},
"review": {
"reprocessing": false,
"createDate": "2020-10-10 00:05:20+0000",
"reviewStatus": "init"
},
"type": "company"
}
# 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
curl -X POST \
'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/info/companyInfo/beneficiaries' \
-H 'Content-Type: application/json' \
-d '{
"applicant": {
"id": "5f6490a55584b510013e87df"
},
"applicantId": "5f6490a55584b510013e87df",
"positions": ["director","ubo"],
"type": "ubo"
}'
# Example response
{
"companyName": "Sum and Substance",
"registrationNumber": "7836733",
"country": "GBR",
"noUBOs": false,
"beneficiaries": [
{
"applicantId": "5e70ac420a975a6f57d26042",
"positions": [
"director",
"shareholder"
],
"type": "ubo"
}
]
}
# 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
curl -X DELETE \
'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/info/companyInfo/beneficiaries/5f6490a55584b510013e87df'
# Example response
{
"ok": 1
}
# 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
curl -X POST \
'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/info/idDoc' \
-H 'content-type: multipart/form-data' \
-F 'metadata={"idDocType":"COMPANY_DOC","country":"GBR"}' \
-F 'content={path to file (file contents)}'
# Example response
{
"idDocType": "COMPANY_DOC",
"country": "USA"
}
# 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
curl -X POST \
'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/status/pending'
# Example response
{
"ok": 1
}
# 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
curl -X GET \
'https://api.sumsub.com/resources/applicants/5ecfbe9ad5ea48743f8dd1b8/one'
# Example response
{
"id": "5ecfbe9ad5ea48743f8dd1b8",
"createdAt": "2020-05-28 13:37:30",
"clientId": "coolclientid",
"inspectionId": "5ecfbe9ad5ea48743f8dd1b9",
"externalUserId": "externalCompanyId",
"info": {
"companyInfo": {
"companyName": "SUMSUB LIMITED",
"registrationNumber": "1555555",
"country": "GBR",
"incorporatedOn": "2018-02-28 00:00:00",
"type": "ltd",
"website": "www.sumsub.com",
"beneficiaries": [
{
"applicantId": "5ecfbecad5ea48743f8dd438",
"positions": ["director"],
"type": "ubo",
"inRegistry": false,
"imageIds": null,
"applicant": null
}
]
}
},
"requiredIdDocs": {
"docSets": [
{
"idDocSetType": "COMPANY",
"types": ["COMPANY_DOC"],
"steps": [
{
"name": "company",
"minDocsCnt": 1,
"idDocTypes": ["COMPANY_DOC"],
"idDocSubTypes": null
},
{
"name": "ubos",
"minDocsCnt": null,
"idDocTypes": null,
"idDocSubTypes": null
}
]
}
]
},
"review": {
"elapsedSincePendingMs": 308656,
"elapsedSinceQueuedMs": 26993,
"reprocessing": true,
"createDate": "2020-05-29 12:22:11+0000",
"reviewDate": "2020-05-29 12:27:19+0000",
"startDate": "2020-05-29 12:26:52+0000",
"reviewResult": {
"reviewAnswer": "GREEN"
},
"reviewStatus": "completed"
},
"lang": "en",
"type": "company"
}
# 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
curl -X PATCH \
'https://api.sumsub.com/resources/applicants/5b76df770a975a1404cbcb60/info/companyInfo' \
-H 'Content-Type: application/json' \
-d '{
"companyName": "Sum and Substance",
"registrationNumber": "7836733",
"country": "GBR",
"website": "sumsub.com",
"noUBOs": false,
"beneficiaries": [
{
"applicantId": "5e95717e0a975a723e187cde",
"positions": null,
"type": "ubo",
"inRegistry": false,
"imageIds": null,
"applicant": null
},
{
"applicantId": "5e9571a30a975a723e187ce9",
"positions": ["shareholder"],
"type": "shareholder",
"inRegistry": false,
"imageIds": null,
"applicant": null
}
]
}'
# Example response
{
"companyName": "Sum and Substance",
"registrationNumber": "7836733",
"country": "GBR",
"website": "sumsub.com",
"noUBOs": false,
"beneficiaries": [
{
"applicantId": "5e95717e0a975a723e187cde",
"positions": null,
"type": "ubo",
"inRegistry": false,
"imageIds": null,
"applicant": null
},
{
"applicantId": "5e9571a30a975a723e187ce9",
"positions": ["shareholder"],
"type": "shareholder",
"inRegistry": false,
"imageIds": null,
"applicant": null
}
]
}
# 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:
curl -X GET \
'https://api.sumsub.com/resources/applicants/5bb8cca10a975a624903cf65/requiredIdDocsStatus'
# Example response:
{
"COMPANY": {
"reviewResult": {
"moderationComment": "Please provide in addition a document, such as the shareholder registry, allowing to establish all the ultimate beneficial owners (natural persons possessing over 25% of the company) and to confirm that the previously declared data on beneficial ownership matches this document.",
"reviewAnswer": "RED"
},
"country": "MLT",
"idDocType": "COMPANY_DOC",
"imageIds": [1473345488],
"imageReviewResults": {
"1473345488": {
"moderationComment": "Please provide in addition a document, such as the shareholder registry, allowing to establish all the ultimate beneficial owners (natural persons possessing over 25% of the company) and to confirm that the previously declared data on beneficial ownership matches this document.",
"reviewAnswer": "RED",
"rejectLabels": ["ADDITIONAL_DOCUMENT_REQUIRED"]
}
}
}
}
# 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
curl -X GET \
'https://api.sumsub.com/resources/checks/latest?type=COMPANY&applicantId=6eea3f5204f940217bcbc05d'
# Example response
{
"checks": [
{
"answer": "GREEN",
"createdAt": "2022-04-05 17:12:31",
"companyCheckInfo": {
"companyName": "SUM AND SUBSTANCE LTD",
"companyNumber": "09688671",
"status": "active",
"type": "ltd",
"source": "UK Government Digital Service",
"sourceUrl": "https://find-and-update.company-information.service.gov.uk/?_ga=2.187069601.885610489.1610661798-159972951.1610661798",
"industryCodes": [
{
"code": "74909",
"description": "Other professional, scientific and technical activities n.e.c."
}
],
"incorporatedOn": "2015-07-16 00:00:00",
"officeAddress": "30 St. Mary Axe EC3A 8BF London England",
"officers": [
{
"fullName": "SEVER (SEVERIUKHIN), Yakov",
"dob": "1986-06-01 00:00:00",
"nationality": "Israeli",
"country": "Cyprus",
"occupation": "Manager",
"appointedOn": "2015-07-16 00:00:00",
"correspondenceAddress": "St. Mary Axe EC3A 8BF London England",
"role": "director",
"status": "active"
}
],
"significantPersons": [
{
"fullName": "Raritex Trade Ltd",
"notifiedOn": "2019-04-18 00:00:00",
"correspondenceAddress": "St. Mary Axe EC3A 8BF London England",
"natureOfControl": "[ \"ownership-of-shares-75-to-100-percent\" , \"voting-rights-75-to-100-percent\" , \"right-to-appoint-and-remove-directors\"]",
"status": "active"
},
{
"fullName": "Mr Yakov Sever",
"dob": "1986-06-01 00:00:00",
"nationality": "Israeli",
"country": "Israel",
"notifiedOn": "2016-04-06 00:00:00",
"correspondenceAddress": "Jean Jaures St. 3570715 Haifa Israel",
"natureOfControl": "[ \"ownership-of-shares-75-to-100-percent\"]",
"status": "resigned"
}
]
}
}
]
}