Skip to main content
POST
/
v1
/
tin
/
verification
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tin: '12-3456789',
    tin_type: 'ein',
    name: 'Acme Corporation',
    reference_id: 'tin_req_12345'
  })
};

fetch('https://api.getpalm.com/v1/tin/verification', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "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"
}

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

Free-form key/value metadata stored on the verification record for partner use.

Example:
{
  "external_id": "tin_789",
  "source": "1099_processing"
}

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_not_configured,
tin_matching_token_unavailable,
tin_matching_invalid_format,
tin_matching_service_unavailable,
tin_matching_unknown_error
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"