Documents
Create verification jobs through the API to analyze identities without going through Trust Swiftly's UI. Use the document status API to retrieve the results.
Direct Document Verification API
This API is for advanced use cases where you need to programmatically submit an identity document (e.g., a driver's license or passport) for analysis. This allows you to build your own document collection UI while still using Trust Swiftly's powerful verification engine on the backend.
Warning: Advanced Use Only By using this API, you are responsible for building your own secure document collection method. You may miss out on important security features and data collection checks provided by Trust Swiftly's hosted UI. We recommend our standard, hosted solution for the most secure and seamless experience.
How It Works: An Asynchronous Flow
Document verification is not instantaneous. The process is asynchronous and follows these steps:
Prerequisite: Ensure a user exists in Trust Swiftly and is assigned to a Verification Template that is configured for a single document check.
Step 1: Create a Verification Job. You upload the document image via a
multipart/form-data
request. The API accepts the job and immediately returns a uniquedoc_id
.Step 2: Poll for Status. You use the
doc_id
to periodically call the status endpoint. This endpoint will initially show a "processing" status.Step 3: Receive Results. After a few seconds, the status endpoint will return a "Success" or "Failure" status, along with the complete analysis data. Alternatively, you can listen for a webhook to be notified of completion.
Prerequisite: Assign a Template to a User
Before you can submit a document for a user, that user must already exist in Trust Swiftly and be assigned to the correct Verification Template. This template tells our system what rules to apply to the document check.
You can do this by calling the Create User or Update User endpoint and providing the appropriate template_id
.
Step 1: Create Document Verification Job
This endpoint accepts a document image and queues it for analysis.
POST
https://{sub-domain}.trustswiftly.com/api/verify/document
Request (multipart/form-data)
user_id
string
Yes
The user ID from Trust Swiftly (e.g., 645
).
template_id
string
Yes
The ID of the template assigned to the user (e.g., tmpl_MTA
).
verify_image
file
Yes
The document image file (JPG, PNG, PDF). Must be less than 10MB.
Example cURL
Request
Note: The @
symbol before the file path tells cURL
to upload the contents of the file.
curl --request POST \
--url https://{sub-domain}.trustswiftly.com/api/verify/document \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'user_id=645' \
--form 'template_id=tmpl_MTA' \
--form 'verify_image=@/path/to/your/drivers_license.jpg'
Success Response
A successful request returns a 200 OK
status and the doc_id
for your new verification job. You must store this ID to check the status in the next step.
{
"success": true,
"doc_id": "313237"
}
Step 2: Get Status of Document Verification Job
After waiting a few seconds, begin polling this endpoint with the doc_id
from Step 1 to check the job status and retrieve the results once complete.
POST
https://{sub-domain}.trustswiftly.com/api/verify/document/status
Request (application/json)
user_id
string
Yes
The user ID from the original request.
doc_id
string
Yes
The document ID received from the job creation endpoint.
Example cURL
Request
curl --request POST \
--url https://{sub-domain}.trustswiftly.com/api/verify/document/status \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"doc_id": "313237",
"user_id": "645"
}'
Success Response
When processing is complete, the document_status
field will change from a processing state to Success
or a failure state. The full extraction and analysis data is contained within the document_data
object.
{
"success": true,
"doc_id": "31323933",
"document_status": "Success",
"document_data": { ... }
}
Failure Response
{
"error_type": "invalid_document_id",
"error_message": "Invalid Document Id"
}
Fail 2
{ "success": false, "doc_id": "31323930",
"document_status": "Failed", "reason": null }
Understanding the document_data
Object
document_data
ObjectThe document_data
object contains a rich set of information. Here are the key sections:
Last updated