Verify TIN (upload TCC)

curl -X POST https://api.vouchmark.com/v1/verifyTin \
  -H "Authorization: Bearer $TOKEN" \
  -F "companyId=cmp_aBcD..." \
  -F "tin=@./tax-clearance.pdf"

{
  "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"
      }
    }
  }
}

POST

verifyTin

curl -X POST https://api.vouchmark.com/v1/verifyTin \
  -H "Authorization: Bearer $TOKEN" \
  -F "companyId=cmp_aBcD..." \
  -F "tin=@./tax-clearance.pdf"

{
  "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"
      }
    }
  }
}

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

string

required

The company the certificate belongs to. You must be the owner.

file

required

The Tax Clearance Certificate. PDF, JPEG, or PNG, up to 10 MB.

curl -X POST https://api.vouchmark.com/v1/verifyTin \
  -H "Authorization: Bearer $TOKEN" \
  -F "companyId=cmp_aBcD..." \
  -F "tin=@./tax-clearance.pdf"

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

{
  "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"
      }
    }
  }
}

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.

Failed verification

{
  "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.

Overview

Auth

Companies

Verifications

Onboarding (KYB)

Widget Embed (Runtime)

Trust Badge

Monitoring

Investigations

Disputes

Vouch AI

Compliance

Wallet & Billing

Developers

Verify TIN (upload TCC)

Form fields

Response

Errors

​Form fields

​Response

​Errors

Form fields

Response

Errors