curl -X POST https://api.vouchmark.com/v1/verifyTin \
-H "Authorization: Bearer $TOKEN" \
-F "companyId=cmp_aBcD..." \
-F "tin=@./tax-clearance.pdf"
{
"success": true,
"message": "TIN verified",
"data": {
"verified": true,
"status": "verified",
"details": {
"aiVerification": true,
"qrVerification": {
"qrFound": true,
"verified": true,
"reason": "QR code matched the certificate details"
}
}
}
}
Verifications
Verify TIN (upload TCC)
Upload a FIRS Tax Clearance Certificate and verify it against the company on file.
POST
/
v1
/
verifyTin
curl -X POST https://api.vouchmark.com/v1/verifyTin \
-H "Authorization: Bearer $TOKEN" \
-F "companyId=cmp_aBcD..." \
-F "tin=@./tax-clearance.pdf"
{
"success": true,
"message": "TIN verified",
"data": {
"verified": true,
"status": "verified",
"details": {
"aiVerification": true,
"qrVerification": {
"qrFound": true,
"verified": true,
"reason": "QR code matched the certificate details"
}
}
}
}
Upload a FIRS Tax Clearance Certificate (TCC). The document is read by the verification model and, on a pass, re-checked against the QR code on the certificate before the TIN is saved to the company. The request is
When the document cannot be confirmed,
Verification is rate limited to 10 attempts per hour per caller.
multipart/form-data and you must own the company.
Form fields
string
required
The company the certificate belongs to. You must be the owner.
file
required
The Tax Clearance Certificate. PDF, JPEG, or PNG, up to 10 MB.
curl -X POST https://api.vouchmark.com/v1/verifyTin \
-H "Authorization: Bearer $TOKEN" \
-F "companyId=cmp_aBcD..." \
-F "tin=@./tax-clearance.pdf"
Response
Every response uses the standard envelope{ success, message, data }. The verification result lives in data as a uniform object: verified (boolean), status (one of verified, pending, failed, not_submitted), an optional reason, an optional suggestions array, and details. On success the verified TIN is written to the company. details reports the two stages: the model read (aiVerification) and the certificate QR check (qrVerification).
{
"success": true,
"message": "TIN verified",
"data": {
"verified": true,
"status": "verified",
"details": {
"aiVerification": true,
"qrVerification": {
"qrFound": true,
"verified": true,
"reason": "QR code matched the certificate details"
}
}
}
}
data.verified is false, data.status is failed, and data.suggestions lists what to fix. The request still succeeds with HTTP 200.
Failed verification
{
"success": true,
"message": "TIN verification failed",
"data": {
"verified": false,
"status": "failed",
"reason": "TIN verification failed",
"details": {
"aiVerification": false,
"qrVerification": null
},
"suggestions": [
"Ensure the document is a valid FIRS Tax Clearance Certificate",
"Make sure the company name matches your registered company name",
"Verify that the TIN number is clearly visible and matches your records",
"Check that the document is not expired and is within the valid period",
"Ensure the document is not digitally altered or manipulated",
"Upload a clear, high-resolution image of the entire document"
]
}
}
Errors
Errors use the same envelope withsuccess: false and a message.
| Status | Body | When |
|---|---|---|
400 | { "success": false, "message": "Missing file or companyId" } | The file or companyId was omitted. |
404 | { "success": false, "message": "Company not found" } | No company matches companyId. |
403 | { "success": false, "message": "Access denied. You can only verify your own company." } | You do not own the company. |
500 | { "success": false, "message": "..." } | Processing failed. |