Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt

Use this file to discover all available pages before exploring further.

The FIRS TIN check confirms a company is registered with the Federal Inland Revenue Service and that the taxpayer name matches the CAC name. It’s the highest-weight verification in the Vouchmark Score (up to 100 points) because tax registration is the single best proof that a company is operating, not just incorporated.

​
How it works

We don’t ask you for the TIN. We resolve it from the RC number by calling the JTB taxpayer API for the company’s classification, then optionally re-verify against an uploaded Tax Clearance Certificate.
1

Kickoff

The check runs automatically once an owner-claimed company has an RC number on file, or you can trigger it manually with POST /v1/check-firstin.
2

Queue

A BullMQ job hits the JTB resolver, trying the relevant classification types (typically 2 for limited companies, 1 for business names).
3

Persist

On success, the TIN and the taxpayer name are written to the company record. On failure, the pending flag is cleared so the UI can fall back to manual upload.

​
Endpoints

curl -X POST https://api.vouchmark.com/v1/check-firstin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"cmp_aBcD..."}'
Successful resolution
{
  "success": true,
  "data": {
    "companyId": "cmp_aBcD...",
    "firsTin": "2522576963525",
    "taxpayerName": "TEKCIFY TECHNOLOGIES LTD",
    "matchedClassification": "2",
    "verified": true,
    "verifiedAt": "2026-05-12T09:14:00Z"
  }
}

​
States while resolving

The dashboard polls GET /v1/dashboard/my-companies?id={companyId} while a kickoff is in flight. The fields to watch:
FieldMeaning
tax.firsttin_pending: trueResolution is in flight.
tax.firsTin set, firsttin_pending: falseResolved successfully.
vouchmark_tools.firstaxClearance_vr: trueThe Tax Clearance Certificate matched.
Both pending flags false and firsTin is emptyResolution failed; fall back to upload.
If the upstream FIRS/JTB API is slow or unreachable, the worker times out at 15s per classification attempt and retries up to twice with a 5-minute backoff. A user-visible spinner falls back to the manual-upload form after ~80 seconds so they’re never stuck.

​
Tax Clearance Certificate upload

If automatic resolution fails (e.g. the company is too new for JTB to have indexed) the owner can upload the Tax Clearance Certificate (TCC). We OCR the PDF, extract the TIN and taxpayer name, and match them against CAC. A successful match awards the full bucket.

​
Common failures

FailureWhat it means
JTB_NO_TINThe resolver returned no TIN for any classification. The company likely isn’t registered with FIRS yet.
NAME_MISMATCHA TIN was found but the registered taxpayer name doesn’t match CAC. We flag this for manual review.
JTB_RATE_LIMITEDWe backed off the JTB API. The job will retry; no action needed.
TCC_UNREADABLEThe uploaded TCC PDF couldn’t be OCR’d. Re-export from FIRS in text-PDF form.