This guide walks you through the process of pushing a file to CheckHub via the API. This is useful when you already have a document (e.g. an ID card scan) and need CheckHub to extract data and run validation — all within a candidate context.
Prerequisites:
- A valid API token (Authorization header). See How to Create Your First API Token.
- The document type ID for the kind of document you want to push (e.g. ID card, driving license).
Process
1. Get or Create the Candidate
You need the candidate's ID and token before you can upload anything. A candidate token looks like this: 02yEXtzgnTPpuabAC
If the candidate already exists, retrieve their token by searching via their ID or private link.
If you need to create a new candidate, use the Create a new candidate endpoint:
- Link to the API documentation: Create a new candidate
The response will return both the candidate ID and token as part of the confirmation payload.
2. Request a Document
Before uploading a file, you need to create a document container that will receive it. This is done through the Candidate Document Type endpoint.
- Link to the API documentation: Candidate Document Type
You need to provide:
- The candidate ID (from step 1)
- The document type ID (e.g. the ID corresponding to "ID card")
This step tells CheckHub what kind of document to expect and prepares the extraction and validation pipeline.
3. Switch to Candidate Token Authentication
Important: From this point onwards, you must authenticate using the candidate token instead of your regular API token. Set the X-CSRF-TOKEN header with the candidate token value.
- Link to the API documentation: Authentication
Example header:
X-CSRF-TOKEN: 02yEXtzgnTPpuabAC4. Upload the File
Upload your file using the Upload file for the candidate document endpoint, authenticated with the X-CSRF-TOKEN.
- Link to the API documentation: Upload file for the candidate document
- Postman collection: Upload file for the candidate document
Attention: Before uploading, set the isMultiple parameter correctly:
- Single-sided document (one file): set
isMultiple=false
- Recto-verso document (front + back, e.g. ID card): set
isMultiple=true
Position Rules
When uploading files, the position parameter determines the order of pages in the generated PDF:
- Recto-verso documents: positions must be strictly
0(recto) and1(verso).
- Multi-part documents: use sequential positions
0, 1, 2, ...— the order determines the pages in the generated PDF.
5. Complete the Upload (only if isMultiple=true)
Good to know: This step is only required when isMultiple=true. If isMultiple=false, the confirmation is automatic once the upload is completed — you can skip this step.
If you set isMultiple=true, you need to finalize the process by calling the Complete upload endpoint.
- Link to the API documentation: Complete single or multiple document upload
- Postman collection: Complete single or multiple document upload
After this step, CheckHub will process the document through the configured extraction and validation pipeline.
Quick Reference
Step | Action | Auth Method |
1 | Get or create candidate | Authorization (API token) |
2 | Request a document | Authorization (API token) |
3 | Switch authentication | X-CSRF-TOKEN (candidate token) |
4 | Upload file | X-CSRF-TOKEN (candidate token) |
5 | Complete upload | X-CSRF-TOKEN (candidate token) |
Need Help?
Access the full API documentation here or explore the Postman collection for ready-to-use request examples.