- Docs
- API reference
- Endpoints and schemas
- KYB API
- Checks
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.
{ "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." } ]}Rules for both tasks
Section titled “Rules for both tasks”top_n: must be1. A higher value returns400.- Request: send the number in the request body and name the task in
attrs(or inproductson an attribute-only request). Atinorssnsent 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.
tin_verification
Section titled “tin_verification”Checks a business TIN, such as an EIN, against a business name.
- Required input:
tin_verificationinattrs(orproducts), atin(ortinswith 1 or 2 values), and a business name. Duplicate TINs are removed after dashes are removed.
Name and TIN pairs
Section titled “Name and TIN pairs”Enigma checks each business name you send against each TIN, one pair at a
time, and stops at the first tin_verified.
- 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_nameleads among names of the same kind. - 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.
ssn_verification
Section titled “ssn_verification”Checks a person’s Social Security number (or ITIN) against the person’s name.
- Required input:
ssn_verificationinattrs(orproducts) and exactly one person withssnset on the person object, not at the top level of the body.
Results
Section titled “Results”Both tasks return these results:
| Result | Meaning |
|---|---|
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. |
New result values can appear, so handle a value your code does not recognize.
When the IRS is unavailable
Section titled “When the IRS is unavailable”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.
Related
Section titled “Related”- Verify a TIN or SSN: the request and response for both checks.
- How checks work: every check, the task object and the source fields.
- Add-ons: every add-on task and its requirements.
- Errors and rate limits: retrying requests safely.