Validate List Matches

Learn how to validate a TIN/Name combination against watchlists and databases using the TINCheck SOAP API.

To validate a TIN/Name against the USPS, DMF, OFAC and banned casino barred lists using the 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:ValidateListMatch>
      <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:ValidateListMatch>
  </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.
- Required for IRS and DMF validations.
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 list match results for more information on each code that might be provided.

Output: ValidateListMatchResult

LISTMATCH_CODE: A numeric code indicating a type of result.
LISTMATCH_DETAILS: A text description of the code returned.

Output: RESULTS

Each list will return results in a separate section called <RESULT>. Within the RESULT section of the response, each list item will contain the following:

OFAC, PEP, PLC, IL, ISA, MO, MS, NJ, NV, SSI, UKE, UVL, DFTO, DPL, DTC, EAR, EPLS, EUS, FBIAVC, FBICAC, FBICC, FBICEI, FBIDT, FBIMWT, FBISI, FBISTI, FBITMW, FBIVCM, FBIWCC, FFI, FSE, GIIN, HHS, and IEO.

Type: The list or result type the result is for.
Code: Result details (must be run through an XML decode method).
Details: A numeric code indicating a type of result.
Count: A text description of the code returned.
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.

List match results

Learn about what your watchlist and database 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. List match results
LISTMATCH_CODE	LISTMATCH_DETAILS
-1	List match not processed
0	No list matches found	✔️
1	Possible list matches found	⚠️
10	Login denied: Invalid user login and/or password
11	Problem processing list match validation request: invalid data {details}
12	Invalid configuration: No lists enabled
13	Invalid list matching request
15	Connection problem
16	List connection problem
17	List match temporarily unavailable
18	Request denied: no more checks available for this account
20	Processing error
21	List match 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 2. List match result types
Type	Code	Details	Count
[ResultType]	0	No list matches found	0	✔️
[ResultType]	1	[ResultType] List: Possible N matches found	N	⚠️

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

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

Sovos Docs

Validate List Matches

Input

Output

List match results

sovos-footer