Skip to main content
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 multipart/form-data and you must own the company.

​
Form fields

​
companyId
string
required
The company the certificate belongs to. You must be the owner.
​
tin
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"
      }
    }
  }
}
When the document cannot be confirmed, 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 with success: false and a message.
StatusBodyWhen
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.
Verification is rate limited to 10 attempts per hour per caller.