Skip to content
Console(opens in a new tab)

TIN and SSN checks

How the two add-on tasks check a business TIN or a person's SSN against IRS records, the results they return, and what to do when the IRS is unavailable.

tin_verification and ssn_verification are add-on tasks. Each checks a number and a name against the IRS TIN Matching system, and reports its outcome in risk_summary.tasks after the package’s standard tasks. This page defines the two tasks and their results; to send the request, see Verify a TIN or SSN.

Here is a tin_verification task from that use case.

Example tin_verification task
{
"task_name": "tin_verification",
"status": "Success",
"result": "tin_verified",
"reason": "The TIN and Name combination matches IRS records",
"sources": [
{
"tin": "123456789",
"name": "ENIGMA TECHNOLOGIES, INC."
}
]
}
  • top_n: must be 1. A higher value returns 400.
  • Request: send the number in the request body and name the task in attrs (or in products on an attribute-only request). A tin or ssn sent without its add-on is ignored.
  • Format: dashes are removed, and the number must then be exactly nine digits with leading zeros kept. Any other value returns 400.

The status of these two tasks carries the value reported by IRS TIN Matching, so it may not be success or failure, as the Success in the example shows. Read result only.

Both tasks are add-ons, so each must be enabled for your account; see Account enablement. Their sources echo the number checked; see Sources for the fields.

Checks a business TIN, such as an EIN, against a business name.

  • Required input: tin_verification in attrs (or products), a tin (or tins with 1 or 2 values), and a business name. Duplicate TINs are removed after dashes are removed.

Enigma checks each business name you send against each TIN, one pair at a time, and stops at the first tin_verified.

  1. Names with a legal-entity designator (Inc, Incorporated, LLC, Limited Liability Company, LLP, PC, Professional Corporation, Co, Company, Ltd or Limited) go first. Otherwise, names keep the order you sent. primary_name leads among names of the same kind.
  2. Each name is paired with every TIN, in order. Names [A, B] and TINs [1, 2] give the pairs (A, 1), (A, 2), (B, 1) and (B, 2).

The task reports the result of the last pair checked. If a later check returns no result, the task keeps the result of the previous pair. Its sources show the TIN of the reported pair, and the name returned with it when one is available.

Each pair checked after the first is an additional IRS check, billed as a separate request.

Checks a person’s Social Security number (or ITIN) against the person’s name.

  • Required input: ssn_verification in attrs (or products) and exactly one person with ssn set on the person object, not at the top level of the body.

Both tasks return these results:

ResultMeaning
tin_verified, ssn_verifiedThe number and name combination matches IRS records.
tin_not_verified, ssn_not_verifiedThe number and name combination does not match IRS records.
tin_not_issued, ssn_not_issuedThe IRS reports that the number is not currently issued.
tin_invalid, ssn_invalidThe number has a valid format, but the IRS does not recognize it as a valid TIN or SSN.
duplicateThe same number was submitted again within a short window, and the IRS rejected the repeat. Wait at least 60 seconds before you resubmit.
not_completedThe check did not complete, usually because the IRS was unavailable. Retry with backoff; see When the IRS is unavailable.

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

The IRS TIN Matching system can be unavailable for minutes or hours. The Enigma status page shows an outage once it has lasted more than five minutes. On not_completed, retry with exponential backoff (1 minute, then 2, then 4, up to 30 minutes between retries). Until the outage ends, the task cannot return a verification result.