Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Enter your API key in the format: sk_test_xxxxx or sk_live_xxxxx

Body

application/json
​
tin
string
required

Tax Identification Number to verify. For EIN use XX-XXXXXXX or 9 digits. For SSN use XXX-XX-XXXX or 9 digits.

Example:

"12-3456789"

​
name
string
required

Name associated with the TIN. For EIN this is the legal business name. For SSN this is the individual's full name (First Last or First Middle Last).

Example:

"Acme Corporation"

​
tin_type
enum<string>
required

Type of TIN being verified — selects the EIN (business) vs SSN (individual) validation path.

Available options:
ein,
ssn
Example:

"ein"

​
reference_id
string

Partner-provided reference ID; echoed back in the response for tracking.

Example:

"tin_req_12345"

​
metadata
object

Custom metadata.

In test mode (sk_test_ key), TIN verification is always simulated — it never contacts the IRS, so no-directive test requests return a deterministic match rather than a real verdict. The reserved key _simulate selects the outcome:

  • match (default) → matched: true, status: completed
  • no_match → matched: false, status: completed
  • unavailable → matched: null, status: pending with unavailable_reason (the IRS-outage shape)

Malformed TINs still return the same tin_matching_invalid_format error as live mode. Ignored in live mode.

Example:

Response

TIN verification completed (matched or not matched) or pending (IRS temporarily unavailable).

​
verification_id
string<uuid>
required

Unique TIN verification ID (UUID v4).

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
object
enum<string>
required

Object type — always the literal string tin_verification.

Available options:
tin_verification
Example:

"tin_verification"

​
tin_type
enum<string>
required

Type of TIN that was verified (echoes the tin_type from the request).

Available options:
ein,
ssn
Example:

"ein"

​
matched
boolean | null
required

Whether the TIN matched the provided name at the IRS. true = match, false = no match, null = match could not be determined (e.g., IRS service unavailable — see unavailable_reason).

Example:

true

​
status
enum<string>
required

Current status of the verification. completed when IRS returned a definitive answer; pending when IRS was unavailable and the caller should retry.

Available options:
pending,
in_progress,
completed,
failed
Example:

"completed"

​
created_at
string<date-time>
required

ISO 8601 timestamp of when the verification record was created.

Example:

"2026-04-17T10:30:00Z"

​
unavailable_reason
enum<string>

Machine-readable reason the verification could not be completed. Only present when status === "pending" or an error occurred.

Available options:
tin_matching_service_unavailable
Example:

"tin_matching_service_unavailable"

​
reference_id
string

Partner-provided reference ID — echoed back only if one was supplied in the request.

Example:

"tin_req_12345"

​
verified_at
string<date-time>

ISO 8601 timestamp of when the TIN was verified against IRS records. Only present when status === "completed".

Example:

"2026-04-17T10:30:01Z"