Validate a Name and TIN combination

Learn how to validate a TIN/Name combination with the TINCheck SOAP API.

You will need to provide your authentication credentials along with any data (input parameters) required by the method to return a result.

The following is an example request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pvs="http://www.TinCheck.com/WebServices/PVSService/">
  <soap:Header/>
  <soap:Body>
    <pvs:ValidateTinName>
      <pvs:TinName>
        <pvs:TIN>123456789</pvs:TIN>
        <pvs:FName>Jane</pvs:FName>
        <pvs:LName>Smith</pvs:LName>
      </pvs:TinName>
      <pvs:CurUser>
        <pvs:UserID></pvs:UserID>
        <pvs:UserLogin>youremail@example.com</pvs:UserLogin>
        <pvs:UserPassword>YourPassword</pvs:UserPassword>
        <pvs:UserEncryption></pvs:UserEncryption>
      </pvs:CurUser>
    </pvs:ValidateTinName>
  </soap:Body>
</soap:Envelope>

Note:

Each xml node in the body content uses the pvs namespace.

Input

The following input parameters are required for this API method:

Input parameters: TinName

TIN: The subject's 9-digit TIN (EIN or SSN). Numbers only, no formatting.
LName: The subject's last name, full name (first and last) or a company name.
FName (Optional): The subject's first name. Use only if the last name is provided separately in the LName field.
GIIN (Optional): The subject's FATCA\FFI GIIN.
Encryption: Leave empty.

Input parameters: CurUser

UserLogin: Your TINCheck login (email address).
UserPassword: Your TINCheck password.
UserEncryption: Leave empty.
UserID: Leave empty.

Output

Read about Name and TIN API results for more information on each code that might be provided.

Output: ValidateTinNameResult

TINNAME_CODE: A numeric code indicating a type of result.
TINNAME_DETAILS: A text description of the code returned.
DMF_CODE: A numeric code indicating a type of result.
DMF_DETAILS: A text description of the code returned.
DMF_DATA: Result details (must be run through an XML decode method).
EIN_CODE: A numeric code indicating a type of result.
EIN_DETAILS: A text description of the code returned.
EIN_DATA: Result details (must be run through an XML decode method).

Output: STATUS

Status: TINCheck system status.
CallsRemaining: The number of calls remaining for the authenticated user.

Name and TIN results

Learn about what your TIN/Name combination validation results mean.

When results are returned, you will see a numeric code alongside a description of the code. Here's a list of each code and description combination you may see when running this type of check:

Note:

⚠️ is considered a "bad" result. ✔️ is a "good" result.

Table 1. TIN/Name results
TINNAME_CODE	TINNAME_DETAILS
-1	TIN/Name validation not processed
0	TIN and name combinations does not match IRS records	⚠️
1	TIN and name combination matches IRS records	✔️
5	TIN entered is not currently issued	⚠️
6	TIN and name combination matches IRS SSN records	✔️
7	TIN and name combination matches IRS EIN records	✔️
8	TIN and name combination matches ITS SSN and EIN records	✔️
10	Login denied: Invalid user login and/or password
11	Invalid data
12	Invalid configuration
13	Invalid TIN matching request	⚠️
14	Duplicate TIN matching request
15	Connection problem
16	IRS connection problem
17	IRS TIN/Name validation temporarily unavailable
18	Request denied: no more checks available for this account
20	Processing error
21	IRS processing error
22	Invalid IRS login
23	Login denied: Invalid user
24	Login denied: Invalid password
25	Login denied:This account has been locked
26	Login denied: Account locked for 24 hours (3+ login attempts)
27	Login denied: Terms not accepted
28	Login denied: Account expired
29	Login denied: No security rights

Table 2. DMF results
DMF_CODE	DMF_DETAILS
-1	Death Master File match not processed
0	No Death Master File match found	✔️
1	Possible Death Master File match found (contains parsable Details)	⚠️
10	Login denied: Invalid user login and/or password
11	Invalid data
12	Invalid configuration
13	Invalid Death Master File Matching request
15	Connection problem
16	DMF connection problem
17	Death Master File Match temporarily unavailable
18	Request denied: no more checks available for this account
20	Processing error
21	Death Master File processing error
23	Login denied: Invalid user
24	Login denied: Invalid password
25	Login denied: This account has been locked
26	Login denied: Account locked for 24 hours (3+ login attempts)
27	Login denied: Terms not accepted
28	Login denied: Account expired
29	Login denied: No security rights

Table 3. EIN results
EIN_CODE	EIN_DETAILS
-1	EIN match not processed
0	No EIN match found	✔️
1	EIN possible match found (contains parsable EIN_DATA)
10	Login denied: Invalid user login and/or password
11	Invalid data
12	Invalid configuration
13	Invalid EIN Matching request
15	Connection problem
16	EIN connection problem
17	EIN Match temporarily unavailable
18	Request denied: no more checks available for this account
20	Processing error
21	EIN processing error
23	Login denied: Invalid user
24	Login denied: Invalid password
25	Login denied: This account has been locked
26	Login denied: Account locked for 24 hours (3+ login attempts)
27	Login denied: Terms not accepted
28	Login denied: Account expired
29	Login denied: No security rights

Table 4. Status results
STATUS	Details
OK	System is functioning normally	✔️

Table 5. Checks results
CallsRemaining	Details
No limit	Monthly plan
Number	Checks remaining

Sovos Docs

Validate a Name and TIN combination

Input

Output

Name and TIN results

sovos-footer