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:

This article focuses on the Document object and the upload made directly using the Treezor API Document endpoints.

Gear icon

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, or image/svg+xml
  • Be converted to base64

Process ​

Uploading documents through the dedicated endpoints can be done in 2 ways.

Documents upload via your application
MethodDescription
1As applicationThe user first uploads documents to your application, so you can check them before uploading them to Treezor.
2As end userYou 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 a document.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 icon

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.

Warning icon

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.

AttributeTypeDescription
userId integerThe unique identifier of the User the document belongs to.
documentTypeId integerThe type of the document. See the Types list below.
name stringThe name of the document, including its extension.
fileContentBase64 stringThe document itself. The file must be base64 encoded.
residenceId integerThe 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.

Gear icon

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:

  1. Request the download URL
  2. Download the document within 30 seconds

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 ​

AttributeTypeDescription
userIdintegerThe unique identifier of the User.
documentStatusstringThe current KYC review status of the document. See table below.
documentTypeIdintegerThe type of document, such as ID Card, driving license, etc. See table below.
namestringThe name of the file, including the extension.
residenceIdintegerThe unique identifier of the User's taxResidence, which is mandatory with documentTypeId set to 24 and 25.
fileContentBase64stringBase64-encoded file.

Types (documentTypeId) ​

documentTypeIdDescription
2Police record
4Company Registration
6CV
7Sworn statement
8Turnover
9Identity card
11Bank Identity Statement
12Proof of address
13Mobile phone invoice
14Invoice, other than Mobile phone invoice
15Residence permit
16Driving license
17Passport
18Proxy granting an employee
19Company registration official paper
20Official tax certificate
21Employee payment notice
22User bank statement
23Business legal status
24Tax Statement
25Exemption Statement
26Liveness result
27Health insurance card
28SIREN
29RBE - List of beneficial owners
31PEP - Assets Declaration
32Professional - Revenue Declaration
33Non-Profit Organisation - Financial Declaration
34Certified Liveness Result
35Natural Person - Revenue and Assets Declaration
36Real Estate - Proof of ownership
37Proof of Securities Exchange Listing
38Identity Verification Form via an Authorized Third Party
39Financial Statement
40Public Accountant Statement
41Family Record Book
42Birth Certificate
43Power of Attorney
44Organisational Chart via an Authorized Third Party
45Official Company Declaration via an Independent Third Party
46Declaration of Activity and Revenues
47Certificate of qualified eSign
48QES Result
49Video Conference Result
50Capitalization table

Status (documentStatus) ​

idcodeStatusdocumentStatusDescription
1600001pendingPENDINGInitial status before upload into the container
3600003pendingPENDINGSuccessfully uploaded into the container
2600002pendingPENDINGSuspected fraud or AML/CFT
4600004canceledCANCELEDCancelled by the user
5600005canceledCANCELEDCancelled by the operator
6600006canceledCANCELEDFailed to write the document into the container
7600007canceledCANCELEDFailed to read the document from the container
9600009yes checkmarkVALIDATEDValidated
8600008no crossREFUSEDRefused
10600010no crossREFUSEDOut of scope
11600011no crossREFUSEDExpired
12600012no crossREFUSEDFalsified
13600013no crossREFUSEDIllegible
14600014no crossREFUSEDTruncated document
15600015no crossREFUSEDTruncated
16600016no crossREFUSEDIncoherent
17600017no crossREFUSEDOther

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 ​

EndpointScope
/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