> ## 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.

# Tax (FIRS TIN) Verification

> Resolve a company's FIRS TIN from its RC number, or confirm it against an uploaded certificate.

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.

```bash Kick off resolution theme={null}
curl -X POST https://api.vouchmark.com/v1/check-firstin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"cmp_aBcD..."}'
```

```json Response theme={null}
{
  "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.

```bash Upload Tax Clearance Certificate theme={null}
curl -X POST https://api.vouchmark.com/v1/verifyTin \
  -H "Authorization: Bearer $TOKEN" \
  -F "companyId=cmp_aBcD..." \
  -F "tin=@./tax-clearance.pdf"
```

```json Verified theme={null}
{
  "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:

```json Failed verification theme={null}
{
  "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](/api-reference/verifications/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](/api-reference/verifications/verify-jtb-tin).

## Reference

* [Verify TIN (upload TCC)](/api-reference/verifications/verify-tin)
* [Verify JTB TIN](/api-reference/verifications/verify-jtb-tin)