- Docs
- API reference
- Endpoints and schemas
- KYB API
- Use cases
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.
https://api.enigma.com/v2/kyb/?package=verify&attrs=tin_verificationCheck 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.
Example
Section titled “Example”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" }'The tin_verification task follows the seven standard verify tasks, which
are left out here.
{ "risk_summary": { "tasks": [ { "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." } ] } ] }, "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890"}Parameters
Section titled “Parameters”x-api-keyRequiredYour API key. Send it from your server only. See Authentication.
attrsRequiredtin_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_nDefault 1Must be
1. A higher value returns400.tinFor a TIN checkThe business TIN: nine digits once dashes are removed. To check 2 TINs, send
tinsinstead. See Several names or TINs.person.ssnFor an SSN checkThe 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.
Several names or TINs
Section titled “Several names or TINs”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.
{ "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.
Response
Section titled “Response”risk_summary.tasks[]The
tin_verificationorssn_verificationtask, after the package’s standard tasks. Find it bytask_nameand branch on itsresult.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[].statusThe value IRS TIN Matching reports, such as
Success, so it is not alwayssuccessorfailure. Readresult, notstatus.tasks[].sources[]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.
Before you rely on it
Section titled “Before you rely on it”- 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 a504. 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_completedusually means the IRS was unavailable, for minutes or hours. See When the IRS is unavailable. - Stored data. The task’s
sourcesecho the TIN or the full SSN you sent. Store and log responses with the same care as the request.
Related
Section titled “Related”- TIN and SSN checks: the full definition of both tasks.
- Add-ons: every add-on task and its requirements.
- Onboard a business: the TIN check together with verification and watchlist screening.