TIN Check

TIN Check matches a US Taxpayer Identification Number (TIN) and a name against IRS records. The same check screens the name against watchlists and can also validate a US mailing address and look up a FATCA GIIN.

It is a standalone product: a check is run by a member of your organization from the dashboard, or by your backend with an API key, not by an end user inside a verification flow. Use it when you need to confirm the tax identity of a US person or company, for example before filing a 1099 or onboarding a US vendor.

Before you start

• The product must be enabled for your organization. If TIN Check does not appear under Compliance in the sidebar, contact the Zyphe team.
• Your role must allow it. Admins, Operators, and AML Officers can run and read checks in both environments. Developers can do so in sandbox only. The full role matrix is maintained in Manage Users.
• You need credits in production. Each production check that returns an answer is charged. See Cost.

Run a check

1. Open Compliance → TIN Check.
2. Select New check.
3. Enter the Name: a person's full name or a company's legal name, as it appears on IRS records.
4. Enter the TIN: the nine digits of a Social Security Number (SSN) or an Employer Identification Number (EIN). Spaces and hyphens are accepted.
5. Optionally, open Address and FATCA details to add a US mailing address, a GIIN, or both. They are verified as part of the same check, at no extra cost.
6. Select Run check. In production the button shows the price of the check.

The answer is returned immediately and the check opens on its own page.

What is stored of the TIN

Only the last four digits are stored, in the form XXXXX6789. The full TIN is used for the lookup and then discarded, so a check cannot be run again from the list: enter the TIN again to repeat it.

Optional details

Field	What the check does with it
Address	Validates the address against the USPS database. This confirms that the address exists, not that it belongs to the subject.
GIIN	Looks the Global Intermediary Identification Number up on the FATCA list of registered foreign financial institutions. The format is XXXXXX.XXXXX.XX.XXX.

When you fill in any part of an address, the street address is required. The state is the two-letter code, and the ZIP code is five digits, or nine with the +4 extension.

The IRS answer

Every stored check carries one of three answers:

Answer	Meaning
Matches IRS records	The TIN and name combination matches IRS records. When the IRS reports it, the check also says whether an SSN record, an EIN record, or both matched.
Does not match	The combination does not match IRS records. Check the spelling of the name against the subject's tax documents.
TIN not issued	The IRS has not currently issued this TIN.

Two situations are errors rather than answers. Nothing is stored and nothing is charged:

• The TIN is refused as invalid. The number is not a valid TIN. Check it and try again.
• The check is unavailable. The check could not be completed. Try again in a few minutes.

The other lookups

The check page lists every lookup the check ran, one row each. Select a row to expand it.

Row	What it tells you
IRS TIN and name check	The IRS answer described above.
EIN name lookup	Whether the EIN is on record under another name. This is for reference only: the record comes from earlier matches and may be out of date.
Death Master File check	Whether the TIN appears on the Social Security Death Master File. A match does not by itself mean the person is deceased, because a number can be reissued.
Address check	The USPS answer for the address you entered. Skipped when no address was provided.
GIIN check	The FATCA list answer for the GIIN you entered. Skipped when no GIIN was provided.
Lists	One row per watchlist the name was screened against, such as the OFAC sanctions list. A flagged list shows how many entries resemble the name, and expands to show those entries.

A possible match is not a confirmed hit

A Possible match means that an entry resembles the name you checked. Watchlist screening is done by name, so common names produce matches that refer to someone else. Review the entries before you act on them.

Turn on Only show validations with a result to hide the lookups that found nothing and the ones that were skipped.

The list of checks

Compliance → TIN Check lists the checks your organization has run in the current environment, newest first. Each row shows:

• Name and TIN, with the TIN masked.
• IRS match: the IRS answer.
• Lists: how many watchlists have entries to review.
• EIN name and DMF: the result of the EIN name lookup and of the Death Master File check.
• Address and GIIN: whether each was checked or not provided.
• Date: when the check was run.

Select a row to open the check. The check page also shows who ran it and what it cost.

Sandbox and production checks are kept apart. Use the dashboard's sandbox toggle to switch between them.

Cost

A production check is charged in credits, at the price shown on the Run check button.

• The charge is made only when the IRS returns an answer: a match, a mismatch, or a TIN that is not issued.
• A TIN refused as invalid and an unavailable check cost nothing.
• The address and GIIN lookups are included in the price of the check.
• If the check cannot be charged, for example because the balance ran out, no result is returned and nothing is stored.

Usage appears with the other products in the Usage This Period table on the Billing page.

Sandbox

Sandbox checks are free and do not run a real lookup. They are answered from sample data, so you can build and demonstrate a process without spending credits or using a real TIN.

An exception to sandbox billing

Other sandbox usage draws on your credit balance, as described in Sandbox mode. TIN Check does not: a sandbox check always costs nothing.

There are two ways to choose the answer of a sandbox check.

Mock check

New mock check appears next to New check in sandbox. It runs a check whose answer you state in the form:

• IRS answer: a match, a mismatch, a TIN that is not issued, or one of the two errors.
• Matching record: for a match, which kind of record matched.
• EIN on record under another name and Possible Death Master File match.
• Lists to flag and the number of entries on each flagged list. Every other list answers with no match.
• Address found by USPS and GIIN found on the FATCA list, which apply when you enter an address or a GIIN.

The check is stored like any other sandbox check.

Reserved TINs

A sandbox check run with New check matches IRS records, unless the TIN is one of these reserved values. No real TIN starts with 000000.

TIN	Answer
000000000	Does not match
000000005	TIN not issued
000000006	Matches, SSN record
000000007	Matches, EIN record
000000008	Matches, SSN and EIN records
000000013	Error: the TIN is refused as invalid
000000017	Error: the check is unavailable
000000101	Matches, with a possible Death Master File match
000000201	Matches, and the EIN is on record under another name
000000301	Matches, with possible matches on two watchlists

An address is found unless its ZIP code is 00000. A GIIN is found unless it is 000000.00000.XX.000.

Run a check from your backend

The same check is available over the API with a Secret API key (zyphe_sk_) in the x-api-key header. Publishable keys are rejected. The sandbox query parameter is required on every request.

Operation	Request
Run a check	POST /sdk/organizations/{organization_id}/tin-checks
List the checks	GET /sdk/organizations/{organization_id}/tin-checks
Get one check	GET /sdk/organizations/{organization_id}/tin-checks/{check_id}
Get the price	GET /sdk/organizations/{organization_id}/tin-checks/quote

curl -X POST \
  "https://api.zyphe.com/sdk/organizations/{organization_id}/tin-checks?sandbox=true" \
  -H "x-api-key: zyphe_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "tin": "12-3456789",
    "address": { "street": "123 Main Street", "city": "Hartford", "state": "CT", "zip": "06103" },
    "giin": "98Q96B.00000.LE.250"
  }'

Only name and tin are required. The response is the stored check: the IRS answer in outcome (MATCH, MISMATCH, or NOT_ISSUED), the masked TIN in tinMasked, the other lookups, and one entry per watchlist in watchlists, each with flagged and possibleMatches.

@zyphe-sdk/node exposes runTinCheck, listTinChecks, getTinCheck, and getTinCheckQuote for these requests:

import { runTinCheck } from '@zyphe-sdk/node'

const { data: check, error } = await runTinCheck(
  { organizationId, isSandbox: true, name: 'Acme Inc', tin: '12-3456789' },
  { apiKey: process.env.ZYPHE_SECRET_API_KEY, environment: 'production' },
)

What applies to a dashboard check applies here too:

• A check is charged in the same way, and GET .../tin-checks/quote returns its price in credits.
• A TIN refused as invalid answers 422, and an unavailable check answers 503. Neither is stored or charged.
• A balance that cannot cover the check answers 402.
• Running checks is limited to 30 requests per minute. Past that, requests answer 429.
• A check run with an API key has no author, so createdByEmail is absent.
• In sandbox, the reserved TINs work as they do in the dashboard. To state the answer instead, send a mock object, which a production request refuses.

The request and response schemas are in the API reference.

Related documentation

• Manage Users
• Billing
• Sandbox mode
• API Keys
• API reference