How to download received documents via API

This guide will help you to download documents received from a candidate using our API.

Before we start...

We recommend you to have a look at Using Postman as a developer tool article before starting document management. We will be on the same page and have the same view on the situation. And if you need to refresh your knowledge about relations between candidates and documents please check How to create a candidate using API

About the candidate

Let’s assume that the candidate is completed and their documents were received. So the candidate has “pending” or “completed” status, and we can proceed with its management.

The next step we have to do is to achieve the "ids" of documents that we want to download.
Use request:
GET /candidateDocumentTypes
In the Params set filter[candidateId] = candidateId from previous request, enable includeDocumentType and includeDocuments params to value "true"

Each candidateDocumentTypes entity has a status.
Here is a full table with document statuses used by our backend.

For our guide, we are interested in "validated" statuses (400, 402, 403)

Validated - means that document was received by the system and checked by internal validators (if they exist) or by Admin.

So, now we have everything that we need to start the document downloading.

Document management ways

1) Download one document file.

For example, you need to download and check only one candidate file, and we have a request which allows doing that.

This request allows downloading 1 file in original format, in PDF format, or a Merge Set (if it is allowed) in .zip format.

It is necessary to use the candidateDocumentId path variable for its performing. You can find in the GET /candidateDocumentTypes response of starting section of the article, the array is named - "documents", the candidateDocumentId presented as "id".

GET /storages/candidate-document/{candidateDocumentId}/download

Paste candidateDocumentId to the path variable, use if it is necessary Params (type of the file which will be downloaded), and send the request.
After, just save the file via the "Save request" button. 

2) Download multiple candidate documents.

The method is used only to download combined files (containing 2 or more candidate documents, for example, ID card both sides, Drive Licence both sides, or International passport filled pages)

It is necessary to use the candidateDocumentTypeId path variable for the request performing. The candidateDocumentTypeId presented as "id" in the GET/candidateDocumentTypes request (article beginning). From this request, you can also understand if the document is multiple. The body must contain param isMultiple, and if the document type is multiple, the value has key = true.

The multiple document example:

Let's request to download combined files.

GET /storages/candidate-document-type/{candidateDocumentTypeId}/download

In the response body you will see a combined pdf file with all related candidate documents.

If the document is not combined you will see a 409 error.

3) Download all files related to a candidate in ZIP.

When a candidate completed all requested documents, it is possible to download all related to the candidate documents in a ZIP file. In the archive must be such documents:

• Document types (original files and converted to PDF);
• Completed Forms (Resources);
• a Merge Set file (if it existed for requested documents).

For a request performing it is necessary to know only a candidate ID.
Paste it to a request path and send the request: 

GET /storages/candidate/{candidateId}/download

 After the request performing click on the "Save Response" button and choose the "Save to a file" option.

In conclusion...

Congratulations, you have all you need for document downloading   

The Troubleshooting & Error handling article can help you if something went wrong with your request.

The article Document management techniques (advanced) will help you to discover new document management ways via CheckHub API.

Please, use the following link for a bug report.

Also, please contact us if you have any questions.