Skip to main content
The FIRS TIN check confirms a company is registered with the Federal Inland Revenue Service. There are two ways to clear it: resolve the TIN automatically from the company’s RC number, or upload a Tax Clearance Certificate and have it verified.

​
Resolve from the RC number

POST /v1/check-firstin kicks off TIN resolution for a company that has an RC number on file. It queues a background job and immediately returns a jobId; the company’s firsTinPending flag is set while the job runs.
Kick off resolution
curl -X POST https://api.vouchmark.com/v1/check-firstin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"cmp_aBcD..."}'
Response
{
  "success": true,
  "message": "TIN verification initiated successfully",
  "jobId": "1234",
  "company": {
    "id": "cmp_aBcD...",
    "companyName": "TEKCIFY TECHNOLOGIES LTD",
    "rcNumber": "8511136",
    "firsTinPending": true
  }
}
Common rejections:
StatusBodyWhen
400{ "success": false, "message": "Company RC number is required for TIN verification" }The company has no RC number.
400{ "success": false, "message": "TIN verification is already in progress. Please wait for completion." }A resolution job is already running.
404{ "success": false, "message": "Company not found or you don't have permission to ..." }The company is missing or not yours.

​
Upload a Tax Clearance Certificate

If automatic resolution doesn’t apply, upload the certificate to POST /v1/verifyTin. The document is read and, on a pass, re-checked against the certificate’s QR code before the TIN is saved.
Upload Tax Clearance Certificate
curl -X POST https://api.vouchmark.com/v1/verifyTin \
  -H "Authorization: Bearer $TOKEN" \
  -F "companyId=cmp_aBcD..." \
  -F "tin=@./tax-clearance.pdf"
Verified
{
  "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" }
    }
  }
}
A failed verification is still a successful request (HTTP 200) and returns data.verified: false with data.status: "failed", a reason, and a suggestions array:
Failed verification
{
  "success": true,
  "message": "TIN verification failed",
  "data": {
    "verified": false,
    "status": "failed",
    "reason": "TIN verification failed",
    "suggestions": [
      "Ensure the document is a valid FIRS Tax Clearance Certificate",
      "Make sure the company name matches your registered company name"
    ],
    "details": {
      "aiVerification": false,
      "qrVerification": null
    }
  }
}
See Verify TIN for the full shape.

​
JTB TIN certificate

A company can also clear the check with a Joint Tax Board (JTB) TIN certificate via POST /v1/verifyJtbTin (multipart field jtbTin). On a pass the JTB TIN is saved to the company’s vouchmark_tools.tin.jtb record. See Verify JTB TIN.

​
Reference