Tax (FIRS TIN) Verification

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:

Status	Body	When
`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.

Get started

Core concepts

Verifications

Reference

Tax (FIRS TIN) Verification

Resolve from the RC number

Upload a Tax Clearance Certificate

JTB TIN certificate

Reference

​Resolve from the RC number

​Upload a Tax Clearance Certificate

​JTB TIN certificate

​Reference

Resolve from the RC number

Upload a Tax Clearance Certificate

JTB TIN certificate

Reference