Documents
Documents are evidence required by Treezor to ensure Users are who they claim to be.
During the KYC/B review, Treezor compares documents to the user’s declarative data. The user is verified if the documents are in order (as well as any other verification requirement).
Users may follow different verification processes depending on their type and distribution country. Processes that result in the creation of a Document object in the Treezor API are uploads through:
- Your application (document endpoints)
- The Document pre-review feature (pre-signed form)
- The Live verification features
- The Qualified Electronic Signature feature
This article focuses on the Document object and the upload made directly using the Treezor API Document endpoints.
Configuration – Documents must:
- Abide by size restrictions (encoded file < 6Mo / original file < 4.5Mo)
- Be in mime type:
application/pdf
,image/jpg
,image/png
,image/tiff
, orimage/svg+xml
- Be converted to base64
Process
Uploading documents through the dedicated endpoints can be done in 2 ways.
Method | Description | |
---|---|---|
As application | The user first uploads documents to your application, so you can check them before uploading them to Treezor. | |
As end user | You upload the documents in the end user’s name with the grant type delegated_end_user JWT. This method is only available if the SCA feature is activated for your environment. It may result in a lower success rate of the KYC review since you don’t review documents first. |
Each method has its advantages and drawbacks. If you are unsure about which to implement, don’t hesitate to contact Treezor.
If we take the first case, the steps are the following:
- User uploads documents to your application (requiring dedicated code on your side)
- You check that the documents are acceptable
- You forward the documents to the
/v1/documents
endpoint. You receive adocument.create
webhook for each document upload. - Once all the documents for a given user are uploaded, you request a review process using the following endpoint:
/v1/users/{id}/Kycreview
- Treezor sends you a
user.kycreview
webhook upon validation or refusal.
Note – More steps may be required
This is a simple example of a KYC Review process. It doesn’t consider multiple methods usage, parent-children hierarchical relations, and additional vigilance measures.
Collect documents
This is the first step if you choose to have the user upload documents to your application or website. You store documents in your cloud infrastructure before passing them on to Treezor.
Your teams should review the documents before uploading them to Treezor. Ensuring documents abide by the requirements results in a higher KYC success rate.
Caution – Regulation
Depending on your local regulations, you may not be allowed to keep or store KYC documents on your infrastructure.
Upload documents
You need to upload all the documents of a given user before requesting a KYC review.
It may include the documents of the children users in the case of a parent-children hierarchical relation.
Parameters
Below are the necessary parameters to create Documents.
Attribute | Type | Description |
---|---|---|
userId | integer | The unique identifier of the User the document belongs to. |
documentTypeId | integer | The type of the document. See the Types list below. |
name | string | The name of the document, including its extension. |
fileContentBase64 | string | The document itself. The file must be base64 encoded. |
residenceId | integer | The unique identifier of the User's Tax Residence. Only required if the documentTypeId is 24 or 25 . |
Request
You can use the following request for each document you need to upload.
Use an access token with the delegated_end_user
grant type if you’re uploading the documents in the end user's name.
bash
curl -X POST {baseUrl}/v1/documents \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}
Here is a {payload}
example:
json
{
"fileContentBase64": "{base64file}",
"userId":123456,
"documentTypeId":9,
"name":"aoak_identity_card.pdf"
}
Returns the Document object.
json
{
"documents": [
{
"documentId": 980190,
"documentTag": null,
"clientId": 929252,
"userId": 100344292, // Associated user
"userFirstname": null,
"userLastname": null,
"name": "Test_id",
"documentStatus": "PENDING", // Document current review status
"documentTypeId": 9,
"documentType": "ID",
"fileName": "980190.pdf",
"thumbFileName": "",
"createdDate": "2024-04-30 14:13:40",
"modifiedDate": "0000-00-00 00:00:00",
"codeStatus": "600003",
"informationStatus": null,
"residenceId": 0,
"temporaryUrl": "",
"temporaryUrlThumb": "" // For displaying thumbnails
}
]
}
Download documents
If you're eligible, you may be able to collect some of the uploaded documents whose documentTypeId
allows for it.
Configuration – Download is not enabled by default
Please contact Treezor to request access to this feature.
Downloading a document is a 2-step process, in which you:
Request the download URL
To request the download URL, you need the corresponding documentId
(available in the document.create
webhook for instance).
bash
curl -X GET {baseUrl}/v1/documents/{documentId}/download \
--header 'Authorization: Bearer {accessToken}' \
Returns the URL to download the document, with all the necessary query parameters for the next step.
json
{
"url": "{documentDownloadUrl}"
}
Download the document
You have 30 seconds to download the document from the moment the presigned URL has been generated in the previous step.
bash
curl -X GET {documentDownloadUrl}
The document is returned in its initial format.
Document key attributes
Attribute | Type | Description |
---|---|---|
userId | integer | The unique identifier of the User. |
documentStatus | string | The current KYC review status of the document. See table below. |
documentTypeId | integer | The type of document, such as ID Card, driving license, etc. See table below. |
name | string | The name of the file, including the extension. |
residenceId | integer | The unique identifier of the User's taxResidence , which is mandatory with documentTypeId set to 24 and 25 . |
fileContentBase64 | string | Base64-encoded file. |
Types (documentTypeId
)
documentTypeId | Description |
---|---|
2 | Police record |
4 | Company Registration |
6 | CV |
7 | Sworn statement |
8 | Turnover |
9 | Identity card |
11 | Bank Identity Statement |
12 | Proof of address |
13 | Mobile phone invoice |
14 | Invoice, other than Mobile phone invoice |
15 | Residence permit |
16 | Driving license |
17 | Passport |
18 | Proxy granting an employee |
19 | Company registration official paper |
20 | Official tax certificate |
21 | Employee payment notice |
22 | User bank statement |
23 | Business legal status |
24 | Tax Statement |
25 | Exemption Statement |
26 | Liveness result |
27 | Health insurance card |
28 | SIREN |
29 | RBE - List of beneficial owners |
31 | PEP - Assets Declaration |
32 | Professional - Revenue Declaration |
33 | Non-Profit Organisation - Financial Declaration |
34 | Certified Liveness Result |
35 | Natural Person - Revenue and Assets Declaration |
36 | Real Estate - Proof of ownership |
37 | Proof of Securities Exchange Listing |
38 | Identity Verification Form via an Authorized Third Party |
39 | Financial Statement |
40 | Public Accountant Statement |
41 | Family Record Book |
42 | Birth Certificate |
43 | Power of Attorney |
44 | Organisational Chart via an Authorized Third Party |
45 | Official Company Declaration via an Independent Third Party |
46 | Declaration of Activity and Revenues |
47 | Certificate of qualified eSign |
48 | QES Result |
49 | Video Conference Result |
50 | Capitalization table |
Status (documentStatus
)
id | codeStatus | documentStatus | Description | |
---|---|---|---|---|
1 | 600001 | PENDING | Initial status before upload into the container | |
3 | 600003 | PENDING | Successfully uploaded into the container | |
2 | 600002 | PENDING | Suspected fraud or AML/CFT | |
4 | 600004 | CANCELED | Cancelled by the user | |
5 | 600005 | CANCELED | Cancelled by the operator | |
6 | 600006 | CANCELED | Failed to write the document into the container | |
7 | 600007 | CANCELED | Failed to read the document from the container | |
9 | 600009 | VALIDATED | Validated | |
8 | 600008 | REFUSED | Refused | |
10 | 600010 | REFUSED | Out of scope | |
11 | 600011 | REFUSED | Expired | |
12 | 600012 | REFUSED | Falsified | |
13 | 600013 | REFUSED | Illegible | |
14 | 600014 | REFUSED | Truncated document | |
15 | 600015 | REFUSED | Truncated | |
16 | 600016 | REFUSED | Incoherent | |
17 | 600017 | REFUSED | Other |
Structure
json
{
"documentId": 0,
"documentTag": "string",
"clientId": 0,
"userId": 0,
"userFirstname": "string",
"userLastname": "string",
"name": "string",
"documentStatus": "string",
"documentTypeId": 0,
"documentType": "sring",
"fileName": "string",
"thumbFileName": "string",
"createdDate": "string",
"modifiedDate": "string",
"codeStatus": "string",
"informationStatus": "string",
"residenceId": 0,
"temporaryUrl": "string",
"temporaryUrlThumb": "string"
}
Endpoints
Endpoint | Scope |
---|---|
/v1/documents Create a document | read_write |
/v1/documents Search for documents | read_only |
/v1/documents/{documentId} Retrieve a specific document based on its id | read_only |
/v1/documents/{documentId} Update a document name | read_write |
/v1/documents/{documentId} Delete a document | read_write |
/v1/documents/{documentId}/download Retrieve a document download URL | read_only |
/v1/users/{userId}/Kycreview Initiate the user KYC review process | read_write |