US TIN Validation

introduction the us tin validation api enables users to verify tax identification numbers (tin) and employer identification numbers (ein) against existing records this api is can help businesses and financial institutions to ensure the authenticity of tax related information provided by companies use cases tax compliance facilitates tax compliance by allowing businesses to validate tins and eins against irs records, ensuring all tax related documents are accurate fraud prevention assists in detecting and preventing tax fraud by verifying the accuracy of tin and ein details submitted by businesses business verification enables verification of business legitimacy through tin/ein matching, crucial for due diligence and risk assessment api details request body curl location 'https //api preproduction signzy us/api/v3/company/tin verification' \\ \ header 'authorization < auth token >' \\ \ header 'content type application/json' \\ \ data raw '{ "searchmethod" "advance", "searchvalue" "200754820", "name" "tesla" }'curl location 'https //api signzy us/api/v3/company/tin verification' \\ \ header 'authorization < auth token >' \\ \ header 'content type application/json' \\ \ data raw '{ "searchmethod" "advance", "searchvalue" "200754820", "name" "tesla" }' request body parameters parameter type description required searchmethod string method of search, either 'advance' or 'basic' yes searchvalue string the tin or ein number should be 9 digits long yes name string the name of the company associated with the tin/ein yes valid ein { "result" { "searchmethod" "advance", "searchvalue" "200754820", "name" "tesla", "isvalidtin" true, "isvalidein" true, "searchresult" { "tinresult" { "validationstatus" "irs match found tin and name combination matches irs ein records", "matchstatus" "ein possible match found ", "possiblematch" "tesla offshore llc" }, "einresult" { "name" "tesla offshore llc", "ein" "200754820", "irsscore" "a", "irsscoreexplanation" "100% match between name and ein in the irs database ", "dbascore" "no", "dbascoreexplanation" "company name is a legal name for the business and not dba", "companyscore" 100, "companyscoreexplanation" "this record appears 100% of times under the associated ein", "providedstatus" "a", "providedstatusexplanation" "address has been verified and is ncoa plus 4", "confidencescore" "a", "confidencescoreexplanation" "this record appears 100% of times under the associated ein", "address" \[ "12514 cutten rd ", "77066", "houston", "tx", "us" ], "formattedaddress" { "street" "12514 cutten rd", "zip" "77066", "state" "tx", "city" "houston", "country" "us" } } }, "sources" \[ { "name" "internal revenue service (irs) tin matching service", "info" "", "primary" true }, { "name" "tin check", "info" "", "primary" true }, { "name" "ein finder", "info" "", "primary" true } ] } } invalid ein { "result" { "ein" "320174439", "validationstatus" false, "irsscore" null, "irsscoreexplanation" null, "dbascore" null, "dbascoreexplanation" null, "confidencescore" null, "confidencescoreexplanation" null, "timestamp" 1695970498 } } response body parameters top level result object field type description result object container for all the response details from the tin verification request result details field type description searchmethod string specifies whether the 'advance' or 'basic' search method was used searchvalue string the tin/ein number that was validated name string the company name associated with the tin/ein isvalidtin boolean true if the tin provided is valid, otherwise false isvalidein boolean true if the ein provided is valid, otherwise false searchresult object detailed container holding results for tin and ein verification searchresult object details field type description tinresult object contains the results of tin validation einresult object contains the results of ein validation tinresult sub object field type description validationstatus string describes the irs match status, e g , "irs match found " matchstatus string provides more detailed match status, e g , "ein possible match found " possiblematch string names the entity that possibly matches the given tin, enhancing user clarity on potential discrepancies einresult sub object field type description name string legal name of the company as registered with the irs ein string the validated employer identification number irsscore string a grade or score (e g , 'a') representing the match quality with irs records irsscoreexplanation string explanation of the irs score, detailing the level of match accuracy dbascore string indicates whether the company operates under a dba (doing business as) dbascoreexplanation string explanation of the dba score, indicating if the name is a legal or trade name companyscore integer numerical score indicating the frequency of records under the associated ein companyscoreexplanation string explains the basis for the company score provided providedstatus string status based on address verification (e g , 'a' for verified) providedstatusexplanation string details the reasons behind the provided status confidencescore string score indicating the overall confidence in the record's validity confidencescoreexplanation string explanation for the confidence score given address array array of strings representing different parts of the company's address formattedaddress object object containing structured address information formattedaddress object field type description street string street address of the company zip string postal code where the company is located state string state abbreviation where the company is registered city string city where the company is located country string country abbreviation (e g , 'us' for united states) sources array field type description sources array list of sources used for the verification process name string name of the data source, e g , "internal revenue service (irs) tin matching service" info string additional information about the source, if any primary boolean indicates whether the source is a primary source of data error code and mapping sample error wrong format tin 400 { "error" { "name" "error", "message" "bad request searchvalue is not correct please make sure it is a 9 digit numeric value no alphabets or special characters allowed ", "status" 400, "reason" "validation error", "type" "bad request", "statuscode" "400" } } upstream error 409 { "error" { "name" "error", "message" "error in getting data from upstream", "status" 409, "reason" "error", "type" "conflict", "statuscode" 409 } } internal server error 500 { "error" { "name" "error", "message" "internal server error", "status" 500, "reason" "error", "type" "conflict", "statuscode" 500 } } error response parameters parameter description error this parameter contains the error error name t he error name error message t he error message error status s tatus of the api error reason reason for error error type type of the error error statuscode request status code from signzy getting help please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better you can reach out to us at help\@signzy com we strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively we value your feedback and are committed to making your experience smooth and enjoyable our team is dedicated to assisting you with any needs you may have thank you for choosing our services we look forward to helping you!