Skip to content
Console(opens in a new tab)

Verify a TIN or SSN

Check a business TIN against the business name, or a person's Social Security number against the person's name, through IRS TIN Matching.

POSThttps://api.enigma.com/v2/kyb/?package=verify&attrs=tin_verification

Check a business TIN, such as an EIN, or a person’s SSN against the name on file with the IRS. Add the check to any Verify a business request: like every use case, it is one POST /v2/kyb/ request, and add-ons combine.

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=tin_verification" \
--header "x-api-key: $ENIGMA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Enigma Technologies",
"address": {
"street_address1": "245 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10016"
},
"tin": "123456789"
}'
x-api-keyheaderRequired

Your API key. Send it from your server only. See Authentication.

attrsqueryRequired

tin_verification, ssn_verification, or both. Each must be enabled for your account. Values are case-sensitive, and a misspelled one is ignored without an error.

top_nqueryDefault 1

Must be 1. A higher value returns 400.

tinbodyFor a TIN check

The business TIN: nine digits once dashes are removed. To check 2 TINs, send tins instead. See Several names or TINs.

person.ssnbodyFor an SSN check

The person’s SSN, on the person object and not at the top level. It is checked against the person’s last_name.

A tin or ssn sent without its add-on is discarded, and the request still returns 200. All body fields are in Request body, and the rules in Validation.

Send up to 2 business names and up to 2 TINs. Enigma checks each name against each TIN, names with a legal-entity designator first, and stops at the first tin_verified. The task reports the last pair checked.

Request body with two TINs
{
"names": ["Enigma Technologies Inc", "Enigma"],
"tins": ["123456789", "987654321"]
}

This body checks Enigma Technologies Inc with each TIN, then Enigma with each TIN, until one pair matches. See Name and TIN pairs.

risk_summary.tasks[]array

The tin_verification or ssn_verification task, after the package’s standard tasks. Find it by task_name and branch on its result.

Show the 6 result values
tin_verified, ssn_verified
The number and name combination matches IRS records.
tin_not_verified, ssn_not_verified
The number and name combination does not match IRS records.
tin_not_issued, ssn_not_issued
The IRS reports that the number is not currently issued.
tin_invalid, ssn_invalid
The number has a valid format, but the IRS does not recognize it as a valid TIN or SSN.
duplicate
The same number was submitted again within a short window, and the IRS rejected the repeat. Wait at least 60 seconds before you resubmit.
not_completed
The check did not complete, usually because the IRS was unavailable. Retry with backoff; see When the IRS is unavailable.
tasks[].statusstring

The value IRS TIN Matching reports, such as Success, so it is not always success or failure. Read result, not status.

tasks[].sources[]array

The TIN of the reported name and TIN pair, or the SSN you sent, echoed back, and a name associated with it when one is available. See Sources.

New result values can appear, so handle a value your code does not recognize.

  • Account enablement. Both checks are add-ons; see Account enablement.
  • Duplicates. Resending the same number within a short window returns duplicate. Wait at least 60 seconds before you resend, including after a 504. See Retry after a 200.
  • Extra checks. With more than one name or TIN, each pair checked after the first is billed as a separate request. See Name and TIN pairs.
  • IRS outages. not_completed usually means the IRS was unavailable, for minutes or hours. See When the IRS is unavailable.
  • Stored data. The task’s sources echo the TIN or the full SSN you sent. Store and log responses with the same care as the request.