> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataspike.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TIN Verification

> Verify that a business name and TIN/EIN matches IRS records.

Verify that a company's legal name and Taxpayer Identification Number (EIN, or SSN for sole proprietors) match IRS records via IRS TIN matching.

## Step 1: Create an applicant

Create an applicant to associate the verification with.

<Tabs>
  <Tab title="Curl">
    ```bash theme={null}
    export API_KEY=<YOUR_API_KEY>

    curl -H "ds-api-token: $API_KEY" \
      -H "Content-Type: application/json" \
      -X POST "https://api.dataspike.io/api/v3/applicants" \
      --data '{"external_id": "company-456"}'
    ```

    Response:

    ```json theme={null}
    {
      "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11"
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "<YOUR_API_KEY>"
    BASE = "https://api.dataspike.io"
    HEADERS = {"ds-api-token": API_KEY, "Content-Type": "application/json"}

    resp = requests.post(f"{BASE}/api/v3/applicants", headers=HEADERS, json={"external_id": "company-456"})
    applicant_id = resp.json()["id"]
    ```
  </Tab>
</Tabs>

## Step 2: Submit TIN verification request

Provide the TIN and the legal business name. The TIN may contain dashes (they are ignored); it must contain 9 digits.

<Tabs>
  <Tab title="Curl">
    ```bash theme={null}
    APPLICANT_ID="01827ed4-c928-7a3c-9a30-7ab7cc169d11"

    curl -H "ds-api-token: $API_KEY" \
      -H "Content-Type: application/json" \
      -X POST "https://api.dataspike.io/api/v4/kyb/$APPLICANT_ID/tin-verification" \
      --data '{
        "tin": "36-2382580",
        "company_name": "DEERE & COMPANY"
      }'
    ```

    Response (HTTP 202):

    ```json theme={null}
    {
      "request_id": "019c9e79-4d64-73e1-9f30-5374f0f57975",
      "status": "initial"
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = requests.post(
        f"{BASE}/api/v4/kyb/{applicant_id}/tin-verification",
        headers=HEADERS,
        json={"tin": "36-2382580", "company_name": "DEERE & COMPANY"},
    )
    request_id = resp.json()["request_id"]
    ```
  </Tab>
</Tabs>

### Request body

| Field          | Type   | Required | Description                                                                             |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `tin`          | string | Yes      | Taxpayer Identification Number (EIN or SSN). Dashes are ignored; must contain 9 digits. |
| `company_name` | string | Yes      | Legal business name to match against the TIN.                                           |

## Step 3: Poll for the result

The check typically completes within a few seconds. Poll the result endpoint until the status changes from `initial`.

<Tabs>
  <Tab title="Curl">
    ```bash theme={null}
    REQUEST_ID="019c9e79-4d64-73e1-9f30-5374f0f57975"

    curl -H "ds-api-token: $API_KEY" \
      "https://api.dataspike.io/api/v4/kyb/result/$REQUEST_ID"
    ```

    Example response (verified):

    ```json theme={null}
    {
      "request_id": "019c9e79-4d64-73e1-9f30-5374f0f57975",
      "status": "verified",
      "verification_type": "tin_verification",
      "response_data": {
        "result": {
          "name": "DEERE & COMPANY",
          "tin": "362382580",
          "status": "TIN Matched",
          "irs_code": 7,
          "irs_reason": "TIN and Name combination matches IRS EIN records"
        }
      },
      "created_at": "2026-02-27T09:41:15.822681Z",
      "completed_at": "2026-02-27T09:41:18.583502Z"
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import time

    while True:
        resp = requests.get(f"{BASE}/api/v4/kyb/result/{request_id}", headers=HEADERS)
        result = resp.json()
        if result["status"] != "initial":
            break
        time.sleep(2)

    print(result)
    ```
  </Tab>
</Tabs>

## Response data

The `response_data.result` object contains the IRS TIN-matching outcome:

| Field        | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `name`       | Business name that was submitted                                    |
| `tin`        | TIN that was submitted (digits only)                                |
| `status`     | Match outcome, e.g. `TIN Matched` or `Did Not Match`                |
| `irs_code`   | IRS TIN-matching code (e.g. `7` = name/TIN matches IRS EIN records) |
| `irs_reason` | Human-readable explanation of the IRS code                          |

## Result statuses

| Status         | Meaning                                                          |
| -------------- | ---------------------------------------------------------------- |
| `verified`     | The name and TIN match IRS records                               |
| `not_verified` | The name and TIN do not match                                    |
| `failed`       | The TIN could not be verified (invalid TIN or an error occurred) |