Skip to content

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.

Warning icon

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

Documents upload for prereview
  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.
Bulb icon

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
}
Info icon

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.

Gear icon

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

Bulb icon

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.

Info icon

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.

ValueStatusDescription
0PENDINGThe document hasn't been pre-reviewed yet.
1REFUSEDThe document was refused during the pre-review.
2VALIDATEDThe 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

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