Skip to main content

KYB Integration

In this page information regarding KYB integration is provided. It is possible to use KYB functionality via our dashboard and UI or via API.

KYB Schema​

Recommended KYB integration & use schema is provided below.

KYB Integration Schema

1. Generate New KYB Token​

1.1. iDenfy Dashboard​

Here's how to generate new KYB token/session.

1.2. API​

In order to create and submit form, firstly KYB token must be created. It could be done by calling KYB token create endpoint.

KYB token create - is required to initiate the form creation and management process for KYB compliance

Generate KYB form token

Authorizations:
API key pair
Request Body schema: application/json
tokenType
required
string (KybTokenTypeEnum)
lifetime
integer [ 0 .. 2592000 ]
Default: 3600

The duration in seconds of KYB token validity.

clientId
required
string [ 1 .. 100 ] characters

A unique string identifying a client on your side.

externalRef
string or null <= 40 characters

Any additional value chosen by you.

(KybLocaleEnum (string or null)) or (NullEnum (any or null))

The default client's language. By default selected by a client's IP address.

flow
string or null <uuid>

KYB flow's id to use for this KYB session.

questionnaire
string or null non-empty

KYB questionnaire's key to use for this KYB session. null for no questionnaire. If not given, the default questionnaire (from your KYB settings) will be used. Ignored when KYB flow is used, then questionnaire is taken according to used flow.

questionnaireRequired
boolean
Default: true

If KYB session should have a questionnaire.

tags
Array of strings <= 5 items [^[^,]+$]
Default: []

List of case-sensitive strings. Each tag can not be longer than 32 characters.

scanRefs
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "tokenType": "FORM",
  • "lifetime": 3600,
  • "clientId": "string",
  • "externalRef": "string",
  • "locale": "en",
  • "flow": "92fe31c9-39b9-47ea-906d-cf09a4c3fa9a",
  • "questionnaire": "string",
  • "questionnaireRequired": true,
  • "tags": [ ],
  • "scanRefs": [
    ]
}

Response samples

Content type
application/json
{
  • "tokenType": "FORM",
  • "tokenString": "string",
  • "expiration": "2019-08-24T14:15:22Z",
  • "isActive": true,
  • "isValid": true,
  • "clientId": "string",
  • "externalRef": "string",
  • "locale": "en",
  • "flow": "92fe31c9-39b9-47ea-906d-cf09a4c3fa9a",
  • "tags": [ ],
  • "scanRefs": [
    ]
}

2. Collect Information​

2.1. iDenfy UI form​

When the token is generated, and the redirect link is created, share it with the client/user so that the form can be filled out and submitted. Most of the information can be found in our dashboard or in the helpdesk documentation, for example:

2.2. API​

note

How to generate link and redirect user to iDenfy KYB UI, if token is created via API - #Create redirect URL

2.2.1. Check Flow​

To know what data should be provided for the form, flow information should be reviewed. It could be done by calling KYB Token Retrieve endpoint.

KYB Token Retrieve - retrieves flow information related to the specific KYB token, detailing the data required for form submission

Retrieve KYB session info

Various info for KYB session.

Authorizations:
KYB token auth

Responses

Response samples

Content type
application/json
{
  • "locale": "en",
  • "flow": {
    }
}
note

This step could be skipped if the same flow is used, as the similar data fields should be provided.

2.2.2. Form Creation​

Create KYB Form by sending request to the endpoint shared below.

Create KYB form - creates a new KYB form linked to the generated KYB token for capturing and submitting necessary compliance information

Create new KYB form

Authorizations:
KYB token auth
Request Body schema: application/json
required
required
object (CompanyInfoRequest)
Array of objects (KybFormDocumentCreateRequest)
Array of any (BeneficiaryRequest)
object (ClientSystemRequest)

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "documents": [
    ],
  • "beneficiaries": [
    ],
  • "clientSystem": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "company": {
    },
  • "documents": [
    ],
  • "beneficiaries": [
    ],
  • "clientSystem": {
    },
  • "meta": {
    }
}

After form is created, it is possible to call:

Info Retrieve - retrieves detailed information about an active KYB session, including various aspects of the company's compliance and verification process

Retrieve KYB session info

Various info for KYB session.

Authorizations:
KYB token auth

Responses

Response samples

Content type
application/json
{
  • "locale": "en",
  • "flow": {
    }
}
Form Update - updates information on an existing KYB form

Update KYB form info

Authorizations:
KYB token authAPI key pair
path Parameters
id
required
string

A unique value identifying this company.

Request Body schema: application/json
required
required
object (CompanyInfoRequest)
object (ClientSystemRequest)

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "clientSystem": {
    }
}

Response samples

Content type
application/json
{
  • "company": {
    },
  • "clientSystem": {
    }
}
Form Partial Update - partially updates specific sections of an existing KYB form

Partially update KYB form info

Authorizations:
KYB token authAPI key pair
path Parameters
id
required
string

A unique value identifying this company.

Request Body schema: application/json
object (CompanyInfoRequest)
object (ClientSystemRequest)

Responses

Request samples

Content type
application/json
{
  • "company": {
    },
  • "clientSystem": {
    }
}

Response samples

Content type
application/json
{
  • "company": {
    },
  • "clientSystem": {
    }
}

It is possible to receive a list with KYB forms associated with particular KYB token. There can be one or zero items in the list, indicating that the KYB form was or was not created.

List KYB forms - lists all KYB forms associated with a particular KYB token, indicating whether a form has been created.

List KYB forms

List KYB forms associated with KYB token. There can be one or zero items in the list, indicating that the KYB form was or was not created.

Authorizations:
KYB token auth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

2.2.3. Documents​

It is possible to manage documents within the KYB form/company. Available endpoints are dedicated to:

List all available documents - lists all documents associated with the KYB form/company

List documents

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
query Parameters
type
Array of strings
Items Enum: "ANNUAL_REPORT" "BANK_STATEMENT" "COMPANY_ADVERSE_MEDIA" "DIRECTORS_REGISTRY" "DIRECTOR_CERT" "DIRECTOR_ONLINE_PRESENCE" "EMAIL_CHECK" "E_SIGNATURE_CERT" "GOOD_STANDING_CERT" "INCORPORATION_ARTICLES" "INCORPORATION_CERT" "INCUMBENCY_CERT" "INDIVIDUAL_ADVERSE_MEDIA" "INFORMATION_STATEMENT" "INVOICE" "NAME_CHANGE_PROOF" "ONLINE_PRESENCE" "ORG_CHART" "OTHER" "OWNERSHIP_STRUCTURE" "PROOF_OF_ADDRESS" "PROOF_OF_DOMAIN" "SHAREHOLDER_CERT" "SHAREHOLDER_ONLINE_PRESENCE" "SHAREHOLDER_REGISTRY" "SOURCE_OF_FUNDS" "SOURCE_OF_WEALTH" "STATE_REGISTRY" "TRADING_STATUS_PROOF" "TRUST_AGREEMENT" "UBO_CERT" "UBO_REGISTRY" "WEBSITE_OVERVIEW"

Multiple values may be separated by commas.

type_Exclude
Array of strings
Items Enum: "ANNUAL_REPORT" "BANK_STATEMENT" "COMPANY_ADVERSE_MEDIA" "DIRECTORS_REGISTRY" "DIRECTOR_CERT" "DIRECTOR_ONLINE_PRESENCE" "EMAIL_CHECK" "E_SIGNATURE_CERT" "GOOD_STANDING_CERT" "INCORPORATION_ARTICLES" "INCORPORATION_CERT" "INCUMBENCY_CERT" "INDIVIDUAL_ADVERSE_MEDIA" "INFORMATION_STATEMENT" "INVOICE" "NAME_CHANGE_PROOF" "ONLINE_PRESENCE" "ORG_CHART" "OTHER" "OWNERSHIP_STRUCTURE" "PROOF_OF_ADDRESS" "PROOF_OF_DOMAIN" "SHAREHOLDER_CERT" "SHAREHOLDER_ONLINE_PRESENCE" "SHAREHOLDER_REGISTRY" "SOURCE_OF_FUNDS" "SOURCE_OF_WEALTH" "STATE_REGISTRY" "TRADING_STATUS_PROOF" "TRUST_AGREEMENT" "UBO_CERT" "UBO_REGISTRY" "WEBSITE_OVERVIEW"

Multiple values may be separated by commas.

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Add new document - uploads a new document to the KYB form/company

Add new document

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
Request Body schema: application/json
required
type
required
string (KybDocumentTypeEnum)
Enum: "INCORPORATION_CERT" "DIRECTOR_CERT" "SHAREHOLDER_CERT" "UBO_CERT" "INCORPORATION_ARTICLES" "SHAREHOLDER_REGISTRY" "DIRECTORS_REGISTRY" "STATE_REGISTRY" "UBO_REGISTRY" "OWNERSHIP_STRUCTURE" "INCUMBENCY_CERT" "TRUST_AGREEMENT" "INFORMATION_STATEMENT" "GOOD_STANDING_CERT" "PROOF_OF_DOMAIN" "PROOF_OF_ADDRESS" "SOURCE_OF_FUNDS" "BANK_STATEMENT" "INVOICE" "ONLINE_PRESENCE" "DIRECTOR_ONLINE_PRESENCE" "SHAREHOLDER_ONLINE_PRESENCE" "WEBSITE_OVERVIEW" "E_SIGNATURE_CERT" "ANNUAL_REPORT" "NAME_CHANGE_PROOF" "TRADING_STATUS_PROOF" "ORG_CHART" "COMPANY_ADVERSE_MEDIA" "INDIVIDUAL_ADVERSE_MEDIA" "EMAIL_CHECK" "SOURCE_OF_WEALTH" "OTHER"
filename
string or null <= 100 characters
file
string <byte>

Base64 encoded document file. Can be: jpeg, jpg, png, gif, webp, heic, heif, pdf files.

Responses

Request samples

Content type
application/json
{
  • "type": "INCORPORATION_CERT",
  • "filename": "string",
  • "file": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "INCORPORATION_CERT",
  • "filename": "string",
  • "file": "http://example.com"
}
Retrieve particular document - retrieves a specific document linked to the KYB form/company

Retrieve document

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "INCORPORATION_CERT",
  • "filename": "string",
  • "file": "http://example.com"
}
Update document - updates an existing document within the KYB form/company

Update document

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Request Body schema: application/json
required
type
required
string (KybDocumentTypeEnum)
Enum: "INCORPORATION_CERT" "DIRECTOR_CERT" "SHAREHOLDER_CERT" "UBO_CERT" "INCORPORATION_ARTICLES" "SHAREHOLDER_REGISTRY" "DIRECTORS_REGISTRY" "STATE_REGISTRY" "UBO_REGISTRY" "OWNERSHIP_STRUCTURE" "INCUMBENCY_CERT" "TRUST_AGREEMENT" "INFORMATION_STATEMENT" "GOOD_STANDING_CERT" "PROOF_OF_DOMAIN" "PROOF_OF_ADDRESS" "SOURCE_OF_FUNDS" "BANK_STATEMENT" "INVOICE" "ONLINE_PRESENCE" "DIRECTOR_ONLINE_PRESENCE" "SHAREHOLDER_ONLINE_PRESENCE" "WEBSITE_OVERVIEW" "E_SIGNATURE_CERT" "ANNUAL_REPORT" "NAME_CHANGE_PROOF" "TRADING_STATUS_PROOF" "ORG_CHART" "COMPANY_ADVERSE_MEDIA" "INDIVIDUAL_ADVERSE_MEDIA" "EMAIL_CHECK" "SOURCE_OF_WEALTH" "OTHER"
filename
string or null <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "type": "INCORPORATION_CERT",
  • "filename": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "INCORPORATION_CERT",
  • "filename": "string",
  • "file": "http://example.com"
}
Partially update document - partially updates a document in the KYB form/company

Partially update document

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Request Body schema: application/json
type
string (KybDocumentTypeEnum)
Enum: "INCORPORATION_CERT" "DIRECTOR_CERT" "SHAREHOLDER_CERT" "UBO_CERT" "INCORPORATION_ARTICLES" "SHAREHOLDER_REGISTRY" "DIRECTORS_REGISTRY" "STATE_REGISTRY" "UBO_REGISTRY" "OWNERSHIP_STRUCTURE" "INCUMBENCY_CERT" "TRUST_AGREEMENT" "INFORMATION_STATEMENT" "GOOD_STANDING_CERT" "PROOF_OF_DOMAIN" "PROOF_OF_ADDRESS" "SOURCE_OF_FUNDS" "BANK_STATEMENT" "INVOICE" "ONLINE_PRESENCE" "DIRECTOR_ONLINE_PRESENCE" "SHAREHOLDER_ONLINE_PRESENCE" "WEBSITE_OVERVIEW" "E_SIGNATURE_CERT" "ANNUAL_REPORT" "NAME_CHANGE_PROOF" "TRADING_STATUS_PROOF" "ORG_CHART" "COMPANY_ADVERSE_MEDIA" "INDIVIDUAL_ADVERSE_MEDIA" "EMAIL_CHECK" "SOURCE_OF_WEALTH" "OTHER"
filename
string or null <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "type": "INCORPORATION_CERT",
  • "filename": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "INCORPORATION_CERT",
  • "filename": "string",
  • "file": "http://example.com"
}
Delete document - deletes a document associated with the KYB form/company

Delete document

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Responses

2.2.4. Beneficiaries​

It is possible to manage beneficiaries within the KYB form/company. Available endpoints are dedicated to:

List beneficiaries - lists all beneficiaries linked to the KYB form/company.

List beneficiaries

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Add new beneficiary - adds a new beneficiary to the KYB form/company.

Add new beneficiary

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
Request Body schema: application/json
parent
string or null non-empty
beneficiaryType
required
string (BeneficiaryTypeEnum)
required
any (RepresentativeInfoCreateRequest)
positions
Array of strings <= 3 items [^[^,]+$]
Default: []

Positions of the beneficiary. Can be shareholder, director, or any other position.

formFiller
boolean

Indicates whether this beneficiary is the filler of the KYB form.

Responses

Request samples

Content type
application/json
Example
{
  • "parent": "string",
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "parent": "string",
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}
Retrieve particular beneficiary - retrieves information on a specific beneficiary within the KYB form/company

Retrieve beneficiary

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this beneficiary.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "parent": "string",
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}
Update beneficiary - updates details of an existing beneficiary

Update beneficiary

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this beneficiary.

Request Body schema: application/json
beneficiaryType
required
string (BeneficiaryTypeEnum)
required
any (RepresentativeInfoRequest)
positions
Array of strings <= 3 items [^[^,]+$]
Deprecated
Default: []

Positions of the beneficiary. Can be shareholder, director, or any other position.

formFiller
boolean

Indicates whether this beneficiary is the filler of the KYB form.

Responses

Request samples

Content type
application/json
Example
{
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "parent": "string",
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}
Partially update beneficiary - partially updates information of a specific beneficiary

Partially update beneficiary

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this beneficiary.

Request Body schema: application/json
beneficiaryType
string (BeneficiaryTypeEnum)
any (RepresentativeInfoRequest)
positions
Array of strings <= 3 items [^[^,]+$]
Deprecated
Default: []

Positions of the beneficiary. Can be shareholder, director, or any other position.

formFiller
boolean

Indicates whether this beneficiary is the filler of the KYB form.

Responses

Request samples

Content type
application/json
Example
{
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "parent": "string",
  • "beneficiaryType": "CEO",
  • "info": {
    },
  • "positions": [ ],
  • "formFiller": true
}
Delete beneficiary - removes a beneficiary from the KYB form/company

Delete beneficiary

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this beneficiary.

Responses

2.2.5. Beneficiaries' Documents​

It is possible to manage beneficiaries' documents using available endpoints to:

List beneficiary documents - lists all documents related to a specific beneficiary within the KYB form/company

List beneficiary documents

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Add new beneficiary document - uploads a new document for a beneficiary

Add new beneficiary document

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string
Request Body schema: application/json
One of
type
required
string (IndividualKybDocTypeEnum)
Enum: "IDENTITY_DOCUMENT" "OTHER"
filename
string or null <= 100 characters
file
string <byte>

Base64 encoded document file. Can be: jpeg, jpg, png, gif, webp, heic, heif, pdf files.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string",
  • "file": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string",
  • "file": "http://example.com"
}
Retrieve particular beneficiary document - retrieves a specific document associated with a beneficiary

Retrieve beneficiary document

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string",
  • "file": "http://example.com"
}
Update beneficiary document - updates an existing document for a beneficiary

Update beneficiary document

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Request Body schema: application/json
One of
type
required
string (IndividualKybDocTypeEnum)
Enum: "IDENTITY_DOCUMENT" "OTHER"
filename
string or null <= 100 characters

Responses

Request samples

Content type
application/json
Example
{
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string",
  • "file": "http://example.com"
}
Partially updates a beneficiary’s document.

Partially update beneficiary document

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Request Body schema: application/json
One of
type
string (IndividualKybDocTypeEnum)
Enum: "IDENTITY_DOCUMENT" "OTHER"
filename
string or null <= 100 characters

Responses

Request samples

Content type
application/json
Example
{
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "type": "IDENTITY_DOCUMENT",
  • "filename": "string",
  • "file": "http://example.com"
}
: Deletes a document linked to a beneficiary

Delete beneficiary document

Authorizations:
KYB token authAPI key pair
path Parameters
beneficiaryId
required
string
companyId
required
string
id
required
string

A unique value identifying this KYB Document.

Responses

2.2.6. Questionnaires​

Questionnaire could be added to the flow, to check whether the form requires questionnaire to be filled up, use endpoints:

Questionnaire list - lists all available questionnaires associated with the KYB form flow

List questionnaires

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Retrieve specific questionnaire - retrieves a particular questionnaire within the KYB process

Retrieve questionnaire

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this questionnaire.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "key": "string",
  • "name": "string",
  • "title": "string",
  • "description": "",
  • "type": "KYC",
  • "sections": [
    ]
}

if there's a need to fill it up, following endpoints could be used to:

Updates the answers to a questionnaire

Update questionnaire answers

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this questionnaire.

Request Body schema: application/json
required
required
object
pattern property
object

Section keys from a questionnaire.

pattern property
object (QuestionnaireAnswersQuestionRequest)

Question keys from a questionnaire.

value
required
any or null

Question answer. Value depends on the question type.

Responses

Request samples

Content type
application/json
{
  • "sections": { }
}

Response samples

Content type
application/json
{
  • "sections": { }
}
Retrieves the answers provided in a questionnaire

Retrieve questionnaire answers

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this questionnaire.

Responses

Response samples

Content type
application/json
{
  • "sections": { }
}
Retrieves all completed questionnaire answers for a form

Retrieve all questionnaires' answers

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]
Deletes answers provided in a questionnaire

Delete questionnaire answers

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string
id
required
string

A unique value identifying this questionnaire.

Responses

2.2.7. Form Submit​

When form is filled, it can be submitted:

Submit Form - submits the completed KYB form for review and processing

Submit KYB form

Submit a filled KYB form for review.

The form will be submitted and you will not be able to edit this KYB form any further unless additional information will be requested during a manual review.

After submission, automatic blacklist and automation processes are executed. Then this KYB form will be reviewed by humans. After manual review, you may receive a webhook callback.

Authorizations:
KYB token auth
path Parameters
id
required
string

A unique value identifying this company.

Responses

note

It is possible to receive webhook to your back-office by setting up notification type COMPANY_SUBMIT

3. Company Review​

3.1. iDenfy Dashboard​

Review onboarded company information.

3.2. API​

To review the form/company, change status endpoint should be used with status -> COMPLETED value.

Change status - changes the status of the KYB form/company to COMPLETED after a review has been conducted

Change company status

Note that the status cannot be changed from PENDING and PROCESSING statuses.

Authorizations:
API key pair
path Parameters
id
required
string

A unique value identifying this company.

Request Body schema: application/json
status
string (KybStatusEnum)

Responses

Request samples

Content type
application/json
Example
{
  • "status": "NEED_TO_PROCESS"
}

Response samples

Content type
application/json
Example
{
  • "status": "NEED_TO_PROCESS"
}
note

It is possible to receive webhook to your back-office when form/company is reviewed by setting up notification type COMPANY_REVIEW

4. Request Information (RI)​

4.1. iDenfy Dashboard​

It is possible to use request more information (RI) functionality in order to ask user/client to update the data on the form/company. Below mentioned notifications, related with:

  • RI (COMPANY_INFO_REQUEST),
  • form submit (COMPANY_SUBMIT),
  • company review (COMPANY_REVIEW)

could be set at Settings -> Notifications.

4.2. API​

First steps are the same as using it via iDenfy UI - RI should be initiated, to receive info/data about it, notification COMPANY_INFO_REQUEST could be set.

4.2.1. Check flow​

Fields could have been changed during RI initiation and differ from the original flow. To know what data should be provided for the form, flow information should be reviewed. It could be done by calling KYB Token Retrieve endpoint.

KYB Token Retrieve - retrieves flow information to review any changes made during the Request Information (RI) process

Retrieve KYB session info

Various info for KYB session.

Authorizations:
KYB token auth

Responses

Response samples

Content type
application/json
{
  • "locale": "en",
  • "flow": {
    }
}

4.2.2. Following steps​

Any changes/actions can be made using the same endpoints as those utilized during the initial filling - steps 2.2.3. to 2.2.6. that are described above.

note

To check whether the form requires questionnaire to be filled up, use questionnaire list endpoint, fill first list item if there's more than one.

Questionnaire list - lists all available questionnaires associated with the KYB form flow

List questionnaires

Authorizations:
KYB token authAPI key pair
path Parameters
companyId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

5. Additional Information​

5.1. Information retrieval using webhooks​

It is possible to receive webhook(s) in the following scenarios:

  • company form is submitted, check webhook typeCOMPANY_SUBMIT,
  • company is reviewed and its status has been changed, check webhook typeCOMPANY_REVIEW,

by navigating to Settings -> Notifications.

5.2. Create redirect URL​

To redirect user to iDenfy KYB UI, redirect URL should be contructed. Append tokenString value from new KYB token respone to https://kyb.ui.idenfy.com/welcome?authToken=.

Example: https://kyb.ui.idenfy.com/welcome?authToken=9TIMoX4oSVmWDJ8qS7zeFUMTh5hi1EcqqLTrPR9r

5.3. Check/retrieve companies​

All forms/companies could be checked/reviewed in the dashboard or retrieved via API by calling KYB list company review webhooks endpoint.

KYB list company review webhooks - retrieves a list of company review webhooks, detailing the status and information of all forms/companies

List company review webhooks

Authorizations:
API key pair
query Parameters
created
Array of strings <date-time> [ items <date-time > ]

Multiple values may be separated by commas.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

5.4. Delete company​

Form/company could be deleted in the dashboard or via API by calling delete company endpoint.

Delete company - deletes the form/company via the API, removing the KYB session and associated information

Delete company

Authorizations:
API key pair
path Parameters
id
required
string

A unique value identifying this company.

Responses

5.5. Generating KYB report​

You can retrieve a report in PDF format about the KYB form/company.

The report contains header with company ID, status, approval status and the following information split up into sections:

  • Submitted company information,
  • Internal company information,
  • Applicants,
  • Questionnaire answers,
  • GOV Checks,
  • Automation statuses,
  • Tags,
  • Audit logs(history),
  • Documents uploaded by customer,
  • Company AML,
  • Adverse media.

Send a HTTP POST request to: https://ivs.idenfy.com/kyb/companies/{id}/pdf/

The request must contain basic auth headers where username is API key and password is API secret. The request must contain JSON with parameter:

Path parameterTypeRequiredSample/available values
idStringYesUnique KYB form/company identifier

Request example: https://ivs.idenfy.com/kyb/companies/neJRWsC3PtHZxQiPwPyVKF/pdf/

5.6. KYB-KYC Integration​

It's possible to have an all-in-one solution for KYB (Know Your Business) and KYC (Know Your Customer) services. Depending on specific integration and required cases, it is possible to:

5.6.1. KYB First Approach​

You can create and submit a KYB form first (see steps 2.2.2. and 2.2.7.). Afterward, it is possible to:

5.6.2. KYC First Approach​

Alternatively, you can onboard/perform KYC verifications first and then manage the KYB form. In this case, make sure that the KYC verification(s) are completed:

  • Gather the list of verification(s) scanRef numbers, and include them when generating a new KYB token (see 1.2. new KYB token via API).
  • Add new beneficiary via API (see step 2.2.4.) using existing KYC verification scanRef.
note

iDenfy recommended way is to use KYC Token automation or create new beneficiary via API as described in step 2.2.4.

Worth mentioning that it is possible to use both services separately and add new beneficiary via API/dashboard depending on integration requirements.