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

# Verify a TIN

> Validate a Tax Identification Number against IRS records — standalone, without a full business or person verification.

export const iconProps = (variant = "default") => {
  const iconVariants = {
    default: "palm-icon-default",
    horizontal: "palm-icon-horizontal",
    stack: "palm-icon-stack",
    navigation: "palm-icon-navigation",
    darkHorizontal: "palm-icon-dark-horizontal",
    dark_stack: "palm-icon-dark-stack",
    getStarted: "palm-icon-get-started"
  };
  return iconVariants[variant] ?? iconVariants.default;
};

export const PalmCard = ({title, description, icon, variant = "default", href, items}) => {
  if (variant === "getStarted") {
    return <div data-card className="pc-wrapper-get-started flex flex-col gap-4 border border-[rgba(4,44,47,0.1)] rounded-2xl p-6">
        <div className="pc-wrapper-inner-get-started">
          {icon !== undefined && <div className="pc-icon-container-get-started">{icon}</div>}
          {title !== undefined && <span className="pc-title-get-started">{title}</span>}
        </div>
        {items && items.length > 0 && <ul className="pc-items-get-started">
            {items.map((item, i) => <li key={i}>
                <a href={item.href} className="pc-item-link-get-started">{item.label}</a>
              </li>)}
          </ul>}
      </div>;
  }
  const variants = {
    default: {
      wrapper: "pc-wrapper-default",
      title: "pc-title",
      description: "pc-description"
    },
    horizontal: {
      wrapper: "pc-wrapper-card",
      title: "pc-title-horizontal",
      description: "pc-description"
    },
    stack: {
      wrapper: "pc-wrapper-stack",
      title: "pc-title-stack",
      description: "pc-description"
    },
    darkHorizontal: {
      wrapper: "pc-wrapper-dark-horizontal",
      title: "pc-title-dark-horizontal",
      description: "pc-description-dark-horizontal"
    },
    navigation: {
      wrapper: "pc-wrapper-navigation",
      title: "pc-title-navigation",
      description: "pc-description-navigation"
    },
    dark_stack: {
      icon: "pc-icon-card",
      title: "pc-title",
      description: "pc-description"
    }
  };
  const styles = variants[variant] ?? variants.default;
  const inner = <a data-card href={href ? href : '#'} className={`no-underline flex flex-col h-full items-start gap-4 p-6 rounded-2xl hover:opacity-80 transition-opacity ${styles.wrapper}`}>
      {icon !== undefined && <span className="icon-wrapper">{icon}</span>}
      {(title !== undefined || description !== undefined) && <div className="flex flex-col min-w-0">
          {title !== undefined && <span className={styles.title}>{title}</span>}
          {description !== undefined && <span className={styles.description}>{description}</span>}
        </div>}
    </a>;
  return inner;
};

<div className="semitransparent-image-wrapper">
  <img src="https://mintcdn.com/palmfinance/rX2qdY1PO1DEWy8L/images/VerifyTinEyeCatch.webp?fit=max&auto=format&n=rX2qdY1PO1DEWy8L&q=85&s=747ca7735bf15b031f3d7a42030441d3" alt="Image showcasing a form to collect information, and the output of a TIN verification request" style={{maxWidth: '1222px', width: '100%', margin: '0' }} width="2444" height="926" data-path="images/VerifyTinEyeCatch.webp" />
</div>

***

## What it does

Verify TIN checks whether a TIN (EIN or SSN) matches the name on file at the IRS. It returns one of three results: matched, not matched, or pending (IRS unavailable).

This is a single-purpose check. It does not run registry lookups, risk assessment, or any other verification step. If you need the full suite of business verification checks, use [Verify a Business](/verify/verify-a-business) — which includes TIN verification as part of the workflow.

## When to use it

Use the standalone TIN endpoint when you need to validate a TIN outside of a full verification flow:

* **1099 processing:** Confirm TINs before filing to avoid IRS B-notices.
* **Pre-verification validation:** Check a TIN before running a full business verification.
* **Bulk TIN hygiene:** Validate TINs across your existing portfolio.
* **SSN verification:** Validate an individual's SSN and name against IRS records, independent of a person verification.

## Request

`POST /v1/tin/verification`

| Field                                                         | Type   | Required | Description                                                                            |
| ------------------------------------------------------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| <span className="initial-bold--success">`tin`</span>          | string | Yes      | EIN (`XX-XXXXXXX` or 9 digits) or SSN (`XXX-XX-XXXX` or 9 digits)                      |
| <span className="initial-bold--success">`name`</span>         | string | Yes      | For EIN: legal business name. For SSN: full name (`First Last` or `First Middle Last`) |
| <span className="initial-bold--success">`tin_type`</span>     | enum   | Yes      | `ein` or `ssn` — determines the validation path                                        |
| <span className="initial-bold--success">`reference_id`</span> | string | No       | Your reference ID, echoed back in the response                                         |
| <span className="initial-bold--success">`metadata`</span>     | object | No       | Free-form key/value pairs stored on the verification record                            |

#### Example request

```bash wrap Bash theme={null}
curl -X POST https://api.getpalm.com/v1/tin/verification \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -d '{
    "tin": "12-3456789",
    "tin_type": "ein",
    "name": "Acme Corporation",
    "reference_id": "tin_req_12345"
  }'
```

## Response

| Field                                                               | Type            | Description                                                           |
| ------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------- |
| <span className="initial-bold--success">`verification_id`</span>    | string (UUID)   | Unique identifier for this TIN verification.                          |
| <span className="initial-bold--success">`object`</span>             | string          | Always `tin_verification`.                                            |
| <span className="initial-bold--success">`tin_type`</span>           | enum            | `ein` or `ssn` (echoes the request).                                  |
| <span className="initial-bold--success">`matched`</span>            | boolean or null | `true` = match, `false` = no match, `null` = could not be determined. |
| <span className="initial-bold--success">`status`</span>             | enum            | `completed`, `pending`, `in_progress`, or `failed`.                   |
| <span className="initial-bold--success">`unavailable_reason`</span> | enum            | Only present when `status` is `pending`. See below.                   |
| <span className="initial-bold--success">`reference_id`</span>       | string          | Echoed from request, if provided.                                     |
| <span className="initial-bold--success">`verified_at`</span>        | datetime        | When the TIN was verified. Only present when `status` is `completed`. |

### Response states

**Completed:** The IRS returned a definitive answer. Check `matched` for the result.

```json wrap JSON theme={null}
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "tin_verification",
  "tin_type": "ein",
  "matched": true,
  "status": "completed",
  "reference_id": "tin_req_12345",
  "created_at": "2026-04-22T05:33:01.665Z",
  "verified_at": "2026-04-22T05:33:01.665Z"
}
```

**Pending:** The IRS TIN matching service is temporarily unavailable. `matched` is `null`. Check `unavailable_reason` and retry later.

```json wrap JSON theme={null}
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "tin_verification",
  "tin_type": "ein",
  "matched": null,
  "status": "pending",
  "unavailable_reason": "tin_matching_service_unavailable",
  "reference_id": "tin_req_12345",
  "created_at": "2026-04-22T05:33:01.665Z"
}
```

### Unavailable reasons

| Reason                                                                            | What it means                                              |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| <span className="initial-bold--success">`tin_matching_service_unavailable`</span> | IRS TIN matching service is temporarily down. Retry later. |
| <span className="initial-bold--success">`tin_matching_token_unavailable`</span>   | Authentication with IRS service failed. Retry later.       |

### Error codes

| Reason                                                                       | What it means                                                    |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| <span className="initial-bold--success">`tin_matching_not_configured`</span> | TIN matching is not enabled for your account. Contact Palm.      |
| <span className="initial-bold--success">`tin_matching_invalid_format`</span> | The TIN format was rejected by the IRS service. Check the input. |
| <span className="initial-bold--success">`tin_matching_unknown_error`</span>  | Unexpected error. Retry, and contact Palm if it persists.        |

## Handling IRS downtime

The IRS TIN matching service has scheduled and unscheduled downtime. When the service is unavailable, the endpoint returns `status: pending` with `matched: null` instead of failing. This lets you distinguish between "TIN didn't match" (`matched: false`) and "we couldn't check" (`matched: null`).

Build your integration to handle the pending state: store the `verification_id`, and retry when your system is ready. Do not treat `matched: null` as a match or a non-match.

## Verify TIN vs full business verification

|                       | Verify TIN                   | Verify a Business                         |
| --------------------- | ---------------------------- | ----------------------------------------- |
| Endpoint              | `POST /v1/tin/verification`  | `POST /v1/business/verification`          |
| What it checks        | TIN + name against IRS only. | Registry, TIN, risk, watchlists and more. |
| Requires workflow     | No.                          | Yes (`workflow_key`).                     |
| Requires vault record | No.                          | Yes (business must exist in vault).       |
| Use case              | Standalone TIN validation.   | Full KYB verification.                    |

For the full parameter reference, see the [API Reference](/api-reference/introduction).

## Next steps

<div className="grid lg:grid-cols-2 gap-6 mt-6">
  <PalmCard variant="navigation" title="Verify a business" description="Confirm that a business entity is real, registered, and in good standing." icon={<Icon className={iconProps("navigation")} icon="arrow-right" />} href="/verify/verify-a-business" />

  <PalmCard variant="navigation" title="Verification reference" description="Risk levels, risk signals, match results, and verification lifecycle details." icon={<Icon className={iconProps("navigation")} icon="arrow-right" />} href="/verify/verification-reference" />

  <PalmCard variant="navigation" title="Start monitoring" description="Track changes to verified businesses in real time." icon={<Icon className={iconProps("navigation")} icon="arrow-right" />} href="/monitor/overview" />

  <PalmCard variant="navigation" title="Onboard overview" description="Find and onboard businesses into your platform." icon={<Icon className={iconProps("navigation")} icon="arrow-right" />} href="/onboard/overview" />
</div>