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

# Resolve FIRS TIN

> Kick off FIRS TIN resolution for a claimed company.

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

<ParamField body="companyId" type="string" required>
  The company must be owned by the caller.
</ParamField>

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

<RequestExample>
  ```bash cURL 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..."}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "TIN verification initiated successfully",
    "jobId": "1234",
    "company": {
      "id": "cmp_aBcD...",
      "companyName": "TEKCIFY TECHNOLOGIES LTD",
      "rcNumber": "8511136",
      "firsTinPending": true
    }
  }
  ```
</ResponseExample>

## Errors

Every error response is shaped `{ "success": false, "message": "..." }`. The `500` queue-failure case also includes an `error` field with the underlying message.

| Status | message                                                                |
| ------ | ---------------------------------------------------------------------- |
| 400    | `Company ID is required`                                               |
| 400    | `Company RC number is required for TIN verification`                   |
| 400    | `TIN verification is already in progress. Please wait for completion.` |
| 404    | `Company not found or you don't have permission to update it`          |
| 404    | `Company not found or you don't have permission to access it`          |
| 500    | `Failed to initiate TIN verification. Please try again.`               |