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

# Verify TIN (upload TCC)

> Upload a FIRS Tax Clearance Certificate and verify it against the company on file.

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

<ParamField body="companyId" type="string" required>
  The company the certificate belongs to. You must be the owner.
</ParamField>

<ParamField body="tin" type="file" required>
  The Tax Clearance Certificate. PDF, JPEG, or PNG, up to 10 MB.
</ParamField>

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

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

<ResponseExample>
  ```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"
        }
      }
    }
  }
  ```
</ResponseExample>

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

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

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