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

1. The end user requests the necessary form to upload the document with the dedicated request:
   /core-connect/users/{userId}/kyc/document
2. The Treezor API answers with the pre-signed form dedicated endpoint.
3. The end user uploads the document using the pre-signed form.
4. You request the download URL of the uploaded document with the dedicated request:
   /core-connect/kyc/documents/{documentId}/preview
5. The Treezor API answers with the download URL to use in the allocated timeframe.
6. You download the document and expose it to your teams for pre-review.
7. 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.
8. 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.

CURL

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 and enctype 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, or image/svg+xml

CURL

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.

CURL

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.

CURL

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

{
    "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.

CURL

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