Skip to main content
POST
/
v1
/
check-firstin
curl -X POST https://api.vouchmark.com/v1/check-firstin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"cmp_aBcD..."}'

{
  "success": true,
  "message": "TIN verification initiated successfully",
  "jobId": "1234",
  "company": {
    "id": "cmp_aBcD...",
    "companyName": "TEKCIFY TECHNOLOGIES LTD",
    "rcNumber": "8511136",
    "firsTinPending": true
  }
}
Queues a background job that resolves the company’s FIRS TIN. The endpoint marks firsTinPending as true, enqueues the job, and returns its ID immediately — the resolved TIN is written back to the company record asynchronously, so poll GET /v1/dashboard/my-companies?id={companyId} for completion.

​
Body

​
companyId
string
required
The company must be owned by the caller.

​
Behaviour

  • The company must have an rcNumber on file; otherwise the request is rejected.
  • If a job is genuinely in flight (vouchmarkTools.tin.firs.pending === true), the request is rejected.
  • If firsTinPending is stale (the worker crashed without clearing it), the endpoint logs the reset and re-queues automatically.
  • If the queue rejects the job, firsTinPending is rolled back to false and a 500 is returned.
curl -X POST https://api.vouchmark.com/v1/check-firstin \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"companyId":"cmp_aBcD..."}'

{
  "success": true,
  "message": "TIN verification initiated successfully",
  "jobId": "1234",
  "company": {
    "id": "cmp_aBcD...",
    "companyName": "TEKCIFY TECHNOLOGIES LTD",
    "rcNumber": "8511136",
    "firsTinPending": true
  }
}

​
Errors

Every error response is shaped { "success": false, "message": "..." }. The 500 queue-failure case also includes an error field with the underlying message.
Statusmessage
400Company ID is required
400Company RC number is required for TIN verification
400TIN verification is already in progress. Please wait for completion.
404Company not found or you don't have permission to update it
404Company not found or you don't have permission to access it
500Failed to initiate TIN verification. Please try again.