To validate a TIN/Name, or check against the USPS, DMF, OFAC and banned casino barred lists using the SOAP API, you’ll 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.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:pvs="http://www.tincheck.com/WebServices/PVSService/">
  <soap:Header/>
  <soap:Body>
    <pvs:ValidateTinNameAddressListMatch>
      <pvs:TinName>
        <pvs:TIN>123456789</pvs:TIN>
        <pvs:FName>Jane</pvs:FName>
        <pvs:LName>Smith</pvs:LName>
      </pvs:TinName>
      <pvs:USPSAddress>
        <pvs:Address1>Apt 310</pvs:Address1>
        <pvs:Address2>123 Main Street</pvs:Address2>
        <pvs:City>Checker</pvs:City>
        <pvs:State>CT</pvs:State>
        <pvs:Zip5>12345</pvs:Zip5>
        <pvs:Zip4>7891</pvs:Zip4>
      </pvs:USPSAddress>
      <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:ValidateTinNameAddressListMatch>
  </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: USPSAddress

• Address1 (Optional): Suite / Apt Number
• Address2: Street Address
• City: Address city
• State: Address state
• Zip5: ZIP Code
• Zip4: +4 (additional portion of ZIPCode)

Input parameters: CurUser

• UserLogin: Your TINCheck login (email address)
• UserPassword: Your TINCheck password
• UserEncryption: leave empty
• UserID: leave empty

Output

See "Interpreting your results" for more information on each code that may be provided.

Output: ValidateTinNameAddressListMatchResult

• REQUESTID: The ID number for this request
• REQUEST_STATUS: A numeric code indicating a type of result
• REQUEST_DETAILS: A text description of the code returned

Output: TINNAME_RESULT

• 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: LISTMATCH_RESULT

• 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, FBICA, 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
  • Result types include: OFAC, PEP, PLC, IL, ISA, MO, MS, NJ, NV, SSI, UKE, UVL, DFTO, DPL, DTC, EAR, EPLS, EUS, FBIAVC, FBICA, FBICAC, FBICC, FBICEI, FBIDT, FBIMWT, FBISI, FBISTI, FBITMW, FBIVCM, FBIWCC, FFI, FSE, GIIN, HHS, and IEO.
• 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

Interpreting your results

When results are returned, you'll 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: ⚠️ = considered a "bad" result   ✔️ = a "good" result