Document pre-review
The Documents pre-review process offers another way to upload documents to Treezor. It includes a built-in pre-validation process.
Users upload files through pre-signed forms. These files are stored on dedicated servers while your teams review them. The actual Document objects are created in the Treezor API once the files are validated.
This is the same method as the one used by the Dashboard.
Caution – The Document object is created after pre-validation
While their structure is similar, objects created during the pre-review process aren't Document object.
Process
- The end user requests the necessary form to upload the document with the dedicated request:
/core-connect/users/{userId}/kyc/document
- The Treezor API answers with the pre-signed form dedicated endpoint.
- The end user uploads the document using the pre-signed form.
- You request the download URL of the uploaded document with the dedicated request:
/core-connect/kyc/documents/{documentId}/preview
- The Treezor API answers with the download URL to use in the allocated timeframe.
- You download the document and expose it to your teams for pre-review.
- Your team members update the document with the dedicated request:
/core-connect/kyc/documents/{documentId}
When doing so, the corresponding Document object is created in the Treezor API. - Once all the documents for a given user are uploaded and pre-validated, you request a review process using the
/v1/users/{userId}/Kycreview
endpoint.
Tip – You can use pre-signed forms without pre-review
To do so, automate the PUT /core-connect/kyc/documents/{documentId}/status
request to set the pre-review status to VALIDATED
and hence creating the Document object in the Treezor API.
Request the upload form
Make the following request to generate the pre-signed form to upload the document.
bash
curl -X POST {baseUrl}/core-connect/users/{userId}/kyc/document \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is {payload}
example for an ID card (documentTypeId=9
).
json
{
"documentType":9,
"metadata":{}
}
Returns the necessary information to upload the document to through the form.
json
{
"documentId":"900f0614-78ff-49e6-90ec-adaa53de7f43",
"form":{
"action":"https:\/\/connect-kyc-files.s3.eu-west-3.amazonaws.com",
"method":"POST",
"enctype":"multipart\/form-data"
},
"formFields":{
"acl":"private",
"key":"1625063017_1370854_9_900f0614-78ff-49e6-90ec-adaa53de7f43_0",
"Content-Type":"",
"X-Amz-Security-Token":"IQo...7x4j", // Truncated for clarity
"X-Amz-Credential":"ASI...est", // Truncated for clarity
"X-Amz-Algorithm":"AWS4-HMAC-SHA256",
"X-Amz-Date":"20210630T142337Z",
"Policy":"eyJ...V19", // Truncated for clarity
"X-Amz-Signature":"5ae...4f7" // Truncated for clarity
},
"expireIn":300
}
Information – The newly exposed endpoint expires after 300 seconds.
The file must therefore be uploaded within 5 minutes of this request.
Upload documents to the form
All the values returned in the previous response are to be used for your request to upload the document:
- The
form
object contains your URL (action
),method
andenctype
for your request. - The
formFields
object contains the form inputs.
You must provide the document in the file
input.
Configuration – Documents must:
- Abide by size restrictions (file < 4.5Mo)
- Be in mime type:
application/pdf
,image/jpg
,image/png
,image/tiff
, orimage/svg+xml
bash
curl -X POST https://connect-kyc-files.s3.eu-west-3.amazonaws.com/ \
-H 'Content-Type: multipart/form-data' \
--form 'acl="{useValueProvidedInThePreviousResponse}"' \
--form 'key="{useValueProvidedInThePreviousResponse}"' \
--form 'Content-Type="{useValueProvidedInThePreviousResponse}"' \
--form 'X-Amz-Security-Token="{useValueProvidedInThePreviousResponse}"' \
--form 'X-Amz-Credential="{useValueProvidedInThePreviousResponse}"' \
--form 'X-Amz-Algorithm="{useValueProvidedInThePreviousResponse}"' \
--form 'X-Amz-Date="{useValueProvidedInThePreviousResponse}"' \
--form 'Policy="{useValueProvidedInThePreviousResponse}"' \
--form 'X-Amz-Signature="{useValueProvidedInThePreviousResponse}"' \
file=@{theDocumentsPath}
Answers with a 204 No Content
HTTP Status Code, signaling that the file was succesfully uploaded.
You may use the /core-connect/users/{userId}/kyc/document
request to retrieve the documentId
necessary for the next step.
View the document
You must download the file to expose it to your teams for validation. Documents can only be downloaded with the following method during the pre-review phase.
Tip – Files are automatically deleted
Validated documents are deleted once the user is validated (i.e., you've received a user.kycreview
webhook with the kycReview
set to 2
).
Use the following request to obtain the URL to download the document.
bash
curl -X GET {baseUrl}/core-connect/kyc/documents/{documentId}/preview \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
Returns the following object containing an url
.
json
{
"url":"https:\/\/dev-connect-kyc-files.s3.eu-west-3.amazonaws.com\/161...4_2?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=IQo...Nce&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASI...est&X-Amz-Date=20210708T092227Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Signature=33b...400",
"contentType":"image\/jpeg",
"duration":300
}
You can now download the file using the url
.
Information – The newly exposed endpoint expires after 300 seconds.
The file must therefore be uploaded within 5 minutes of this request.
Pre-validate documents
Your teams may either validate of refuse a document by updating its pre-review status
.
Value | Status | Description |
---|---|---|
0 | PENDING | The document hasn't been pre-reviewed yet. |
1 | REFUSED | The document was refused during the pre-review. |
2 | VALIDATED | The document was validated during the pre-review. As a result, a Document object is created in the Treezor API. |
In addition, the comment
mandatory attribute allows you to specify why the document is accepted or refused.
Validation of the document
Here is an example of request to pre-validate the document.
bash
curl -X PUT {baseUrl}/core-connect/kyc/documents/{documentId}/status \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
-d '{
"status": 2,
"comment": "This document is fine" #Avoid special characters
}'
Returns the updated object.
json
{
"documentId":"1ca27e96-0cf1-45ba-82ea-404f850c2264",
"documentType":9,
"status":2,
"userId":1370854,
"createdAt":"2021-03-08T14:13:00+00:00",
"metadata":{
"creationdate":"2021-03-08T14:13:00.438Z",
"treezor_document_id":"383597" // Created Document object id
},
"comment":"This document is fine",
"updatedAt":"2021-05-14T11:19:46+00:00"
}
Once validated, the corresponding Document object is created in the Treezor API and Treezor sends the corresponding document.create
webhook.
Since the metadata
may take a few seconds to be populated, you might not receive it with the API response right away. However, the webhook for document creation contains all the information you need.
Webhook example
json
{
"webhook":"document.create",
"object_payload":{
"documents":[
{
"documentId":"383597", // treezor_document_id
"documentTag":"",
"clientId":"929252",
"userId":"1370854",
"userFirstname":"Alex",
"userLastname":"Oak",
"name":"1ca27e96-0cf1-45ba-82ea-404f850c2264", // pre-review document uuid
"documentStatus":"PENDING",
"documentTypeId":"9",
"documentType":"ID",
"fileName":"1012512.png",
"thumbFileName":"",
"createdDate":"2024-07-17 14:34:47",
"modifiedDate":"0000-00-00 00:00:00",
"codeStatus":"600003",
"informationStatus":"",
"residenceId":"0",
"totalRows":1
}
]
},
"object_id":"1012512",
"object":"document",
"webhook_created_at":17212196888641,
"webhook_id":"ca1a6f2f-7d2f-46b8-a1dc-b76e5e656ee6",
"object_payload_signature":"IuXf8vyqvswwPKwadf/Encpwe/RiW8ixxxxlLLLM3QY="
}
Refusal of the document
Here is an example of request to refuse the document.
bash
curl -X PUT {baseUrl}/core-connect/kyc/documents/{documentId}/status \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
-d '{
"status": 1,
"comment": "This document is not suitable" #Avoid special characters
}'
Returns the updated object.
json
{
"documentId":"1ca27e96-0cf1-45ba-82ea-404f850c2264",
"documentType":9,
"status":1,
"userId":1370854,
"createdAt":"2021-03-08T14:13:00+00:00",
"metadata":{
"creationdate":"2021-03-08T14:13:00.438Z"
},
"comment":"This document is not suitable",
"updatedAt":"2021-07-08T09:31:03+00:00"
}
Structure
The file for pre-review is slightly different from the actual Document object, starting with the fact that the documentId
is an UUID and the status
indicates the pre-validation status.
json
[
{
"documentId": "bb18a003-050c-4acb-b33e-e44f26534b87",
"documentType": 9,
"status": 0,
"userId": 100554428,
"createdAt": "2024-07-15T13:45:48+00:00",
"metadata": [],
"comment": "",
"updatedAt": "2024-07-15T15:48:23+02:00"
}
]
Endpoints
Endpoint | Scope |
---|---|
/core-connect/users/{userId}/kyc/document Retrieve the pre-review documents for a user | legal |
/core-connect/users/{userId}/kyc/document Create a pre-signed form to upload document | read_write |
/core-connect/kyc/documents/{documentId}/preview Retrieve a pre-signed URL to download the document | legal |
/core-connect/kyc/documents/{documentId}/status Update the pre-review document status | legal |
/core-connect/kyc/documents/{documentId} Delete a pre-review document | legal |
/v1/users/{userId}/Kycreview Initiate the user KYC review process | read_write |