> ## 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 JTB TIN

> Upload a JTB/FIRS TIN certificate and verify it against the company on file.

Upload a Joint Tax Board (JTB) TIN certificate. The document is compared against a reference JTB certificate by the verification model. On a pass, the TIN is written to the company's `vouchmark_tools.tin.jtb` record. 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.
</ParamField>

<ParamField body="jtbTin" type="file" required>
  The JTB TIN certificate. PDF, JPEG, or PNG, up to 10 MB.
</ParamField>

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

## Response

<ResponseExample>
  ```json Verified theme={null}
  {
    "success": true,
    "message": "JTB TIN verification successful",
    "verificationResult": {
      "tinNumber": "2522576963525",
      "companyMatch": "MATCH",
      "documentValidity": "VALID",
      "authenticityScore": 90,
      "confidenceScore": 85,
      "reason": "Verification completed"
    },
    "company": {
      "id": "cmp_aBcD...",
      "companyName": "TEKCIFY TECHNOLOGIES LTD",
      "jtbtin": "2522576963525",
      "jtbtin_vr": true
    }
  }
  ```
</ResponseExample>

When the document fails the response is `400` with `verificationResult` and `suggestions`.

```json Failed theme={null}
{
  "success": false,
  "message": "JTB TIN verification failed",
  "verificationResult": {
    "tinNumber": "NOT_FOUND",
    "companyMatch": "MATCH",
    "documentValidity": "VALID",
    "authenticityScore": 30,
    "confidenceScore": 40,
    "reason": "Could not confirm the certificate"
  },
  "suggestions": [
    "Ensure the document is a valid JTB/FIRS TIN certificate",
    "Check that the company name matches exactly",
    "Verify the TIN number is clearly visible",
    "Ensure the document is not expired or damaged",
    "Try uploading a clearer, higher quality image",
    "Verify the document format matches official JTB TIN certificates"
  ]
}
```

## Errors

| Status | Body                                                                                                                | When                                      |
| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `400`  | `{ "success": false, "error": "Missing file or company ID" }`                                                       | The file or `companyId` was omitted.      |
| `404`  | `{ "success": false, "error": "Company not found" }`                                                                | No company matches `companyId`.           |
| `403`  | `{ "success": false, "error": "Access denied. You can only verify your own company." }`                             | You do not own the company.               |
| `500`  | `{ "success": false, "error": "We couldn't process your document right now. Please try again.", "details": "..." }` | The model could not process the document. |

Verification is rate limited to 10 attempts per hour per caller.