{ "openapi": "3.0.3", "info": { "title": "TIN Comply API", "version": "1.0", "description": "Real-time IRS TIN matching, sanctions screening, address, EIN, FATCA, LEI, NPI, Medicare and FMCSA checks.\n\nAuthenticate with the X-API-Key header, using a key from Admin \u003E API Key Management. Each call to validate or a per-service endpoint uses one check, whether it runs one service or several.\n\nA result with completed false is not ready yet because its upstream source was unavailable. It is retried automatically; call request-details with the request id later to get the finished result.", "contact": { "name": "TIN Comply", "url": "https://www.tincomply.com/contact" } }, "externalDocs": { "description": "API reference", "url": "https://www.tincomply.com/help-center/api" }, "servers": [ { "url": "https://www.tincomply.com/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Tax ID \u0026 business" }, { "name": "Screening" }, { "name": "International entities" }, { "name": "Healthcare \u0026 carriers" }, { "name": "Multi-service" }, { "name": "Results" }, { "name": "Service status" } ], "paths": { "/validate/irs-tin-name-matching": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "irsTinNameMatching", "summary": "IRS TIN matching", "description": "Checks a TIN and name combination against IRS records in real time and returns the IRS result code. Works for EINs, SSNs and ITINs. No IRS e-Services enrollment is required.\n\nCodes 0, 6, 7 and 8 are matches. Codes 1 through 5 are failures. When a match fails, a corrected W-9 is the usual next step.\n\n**Possible values for result**\n\n| Value | Meaning |\n|---|---|\n| 0 | TIN and Name match |\n| 1 | TIN was missing or not 9-digit numeric |\n| 2 | TIN entered is not currently issued |\n| 3 | TIN and Name combination does not match IRS records |\n| 4 | Invalid TIN Matching request |\n| 5 | Duplicate TIN Matching request |\n| 6 | TIN and Name combination matches IRS SSN records |\n| 7 | TIN and Name combination matches IRS EIN records |\n| 8 | TIN and Name combination matches IRS SSN and EIN records |\n\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| 0, 6, 7 or 8 | Match. Keep the request id with the payee record as evidence of the check. |\n| 6 when you expected an EIN, or 7 when you expected an SSN | The TIN is valid but is a different type than the payee claimed. Confirm the entity type and TIN on the W-9. |\n| 1 | The TIN is not 9 digits. Fix the data entry and send it again. |\n| 2 | The IRS has not issued this TIN. Hold payment and request a corrected W-9. |\n| 3 | The name and TIN do not match. Request a corrected W-9 with the legal name exactly as the IRS has it, and check again. Mismatches left on filed 1099s lead to IRS B-notices and backup withholding. |\n| 4 | The IRS rejected the request as invalid. Check that both tin and name were sent and that the name has no unusual characters. |\n| 5 | The same TIN and name were already checked. Use the earlier result. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-irs-tin-name-matching" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IrsTinNameMatchingRequest" }, "example": { "tin": "123-12-1234", "name": "JOHN SMITH" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IrsTinNameMatchingResponse" }, "example": { "id": "BZ5CF5Z2q0SwIBmhZylJggxp", "request": { "tin": "XXXXX1234", "name": "JOHN SMITH", "requestDate": "2026-10-01T20:23:41Z", "requestedServices": "irs-tin-name-matching" }, "irsTinNameMatchingResult": { "message": "TIN and Name combination does not match IRS records", "result": 3, "completed": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/company-name-lookup-by-ein": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "companyNameLookupByEin", "summary": "Company name by EIN", "description": "Submit an EIN and get back the registered business name associated with it. Useful when a vendor supplies an EIN but not the exact legal name.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| found is true | Compare name with the name your vendor gave you. If they differ, ask for the legal name and run IRS TIN matching with it. |\n| found is false | No name is on record for this EIN in our sources, which does not prove it is invalid. Run IRS TIN matching with the name the payee supplied. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-company-name-lookup-by-ein" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyNameLookupByEinRequest" }, "example": { "tin": "13-0871985" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyNameLookupByEinResponse" }, "example": { "id": "Yk2pW8sQnE6cRtV1aZbLm0Xo", "request": { "tin": "XXXXX1985", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "company-name-lookup-by-ein" }, "companyNameLookupByEinResult": { "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "message": "EIN lookup match found", "found": true, "completed": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/company-ein-lookup-by-name": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "companyEinLookupByName", "summary": "EIN by company name", "description": "Submit a company name and receive candidate EINs ranked by name-match confidence. EINs are masked in the response; reveal the one you need with the reveal-ein endpoint below.\n\nEINs come back masked. To get the full EIN for the candidate you want, call reveal-ein below with this request\u0027s id and the candidate\u0027s id.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| One candidate at high confidence | Call reveal-ein for it, then confirm the EIN and name with IRS TIN matching before you rely on it. |\n| Several candidates | Narrow them down first, for example by address with company details lookup. Each lookup includes one reveal, so choose before you reveal. |\n| No results | Try the exact legal name (Inc versus Incorporated, with or without punctuation), or ask the company for a W-9. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-company-ein-lookup-by-name" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEinLookupByNameRequest" }, "example": { "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEinLookupByNameResponse" }, "example": { "id": "3vQd8kLpZ0mYtN5rWcXaE2bF", "request": { "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "company-ein-lookup-by-name" }, "companyEinLookupByNameResult": { "completed": true, "results": [ { "id": "kIBnBIgsE022jdmzRAKrYgbO15e142clmUSasX6Rr8UkdgKU", "name": "INTERNATIONAL BUSINESS MACHINES CORP", "ein": "13-XXXXX66", "confidence": 100 }, { "id": "3aw5invM9UKeWtqgLB8mcQKz4Hywib4SPEWOsoTXjqZCdADW", "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "ein": "13-XXXXX85", "confidence": 100 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/request-details/reveal-ein": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "revealEin", "summary": "Reveal EIN", "description": "Step two of an EIN lookup: unmasks the EIN of the candidate you choose from the company-ein-lookup-by-name results. Each lookup includes one reveal; it does not use another check.\n\nThe response id is the candidate\u0027s id. Requires an API key with the History permission. This endpoint always returns HTTP 200. A body with a message field instead of an ein means the reveal was not permitted (for example, a different EIN on this request was already revealed).", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-company-ein-lookup-by-name#request-details-reveal-ein" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealEinRequest" }, "example": { "id": "3vQd8kLpZ0mYtN5rWcXaE2bF", "resultId": "kIBnBIgsE022jdmzRAKrYgbO15e142clmUSasX6Rr8UkdgKU" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealEinResponse" }, "example": { "id": "kIBnBIgsE022jdmzRAKrYgbO15e142clmUSasX6Rr8UkdgKU", "ein": "13-5157866", "name": "INTERNATIONAL BUSINESS MACHINES CORP" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/address-validation": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "addressValidation", "summary": "Address validation", "description": "Verifies and standardizes a US mailing address against USPS records, adds the ZIP\u002B4, county and congressional district, and lists every correction made to your input.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| found is true | Save the standardized address and ZIP\u002B4 back to your record. corrections lists what changed. |\n| found is false | USPS could not confirm the address. Ask the payee to confirm it before you mail checks or 1099s. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-address-validation" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "example": { "street": "PO BOX 218", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "example": { "id": "Pq7rT2vWx9yZa1bC3dE5fG6h", "request": { "street": "PO BOX 218", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "address-validation" }, "addressValidationResult": { "street": "218 PO BOX", "suite": "", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598", "zip4": "0218", "dpbc": "18", "congressionalDistrict": "17", "countyName": "WESTCHESTER", "message": "Address was confirmed as valid", "completed": true, "found": true, "corrections": [ "PO BOX match.", "ZIP\u002B4 corrected." ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/company-details-lookup-by-name-address": { "post": { "tags": [ "Tax ID \u0026 business" ], "operationId": "companyDetailsLookupByNameAddress", "summary": "Company details", "description": "Look up a business by legal name, by address, or both. Returns matching companies with their address, phone, website and other public attributes, each with a match confidence.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| A result at high confidence | Use its properties to fill in or confirm your record: address, phone, website. |\n| Only low-confidence results, or none | Send more of what you know (the full address as well as the name) and try again. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-company-details-lookup-by-name-address" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetailsLookupByNameAddressRequest" }, "example": { "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "street": "1 NEW ORCHARD RD", "city": "ARMONK", "state": "NY", "zip5": "10504" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetailsLookupByNameAddressResponse" }, "example": { "id": "Hk8sJ2nQ4wE6rT0yUiOpLa3S", "request": { "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "street": "1 NEW ORCHARD RD", "city": "ARMONK", "state": "NY", "zip5": "10504", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "company-details-lookup-by-name-address" }, "companyDetailsLookupByNameAddressResult": { "completed": true, "anyFiltered": false, "results": [ { "name": "International Business Machines Corporation", "type": "Organization", "confidence": 100, "properties": { "names": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "address": "1 NEW ORCHARD RD, ARMONK, NY 10504-1722", "country": "United States", "phonenumbers": "(914) 499-1900", "relatedWebsites": "https://www.ibm.com" } } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/list-sanctions": { "post": { "tags": [ "Screening" ], "operationId": "listSanctions", "summary": "Sanctions screening", "description": "Screens a person or business name against more than 330 sanctions and watchlists, including OFAC SDN, the Consolidated Screening List, SAM exclusions, FinCEN, BIS, EU and UN, with fuzzy matching and alias detection. Hits below your account\u0027s match threshold are filtered out.\n\nA hit is a lead for review, not a determination. Compare the list source and the returned identifiers (aliases, addresses, IDs) against your record before acting.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| No results | Clear. Keep the request id as evidence of the screening. |\n| anyFiltered is true | The name is on a list your account does not screen against. If that list matters to your program, enable it in the portal and screen again. |\n| One or more results | Hold the payment or onboarding and review each hit: the list it came from, aliases, addresses and identifiers. |\n| A hit you confirm is the same party | Do not pay. Escalate to your compliance officer; OFAC and other regimes have their own blocking and reporting rules. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-list-sanctions" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSanctionsRequest" }, "example": { "name": "INTERNATIONAL BUSINESS MACHINES" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSanctionsResponse" }, "example": { "id": "Wm3nB5vC7xZ9aS1dF2gH4jK6", "request": { "name": "INTERNATIONAL BUSINESS MACHINES", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "list-sanctions" }, "listSanctionsMatchResult": { "completed": true, "anyFiltered": false, "results": [ { "name": "INTERNATIONAL BUSINESS MACHINES", "type": "Organization", "confidence": 75, "list": "Business Identifier Code (BIC) Reference Data", "properties": { "names": "INTERNATIONAL BUSINESS MACHINES", "sWIFTBIC": "IBMXUS33", "country": "United States" }, "related": [], "relationships": [] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/fatca-giin": { "post": { "tags": [ "International entities" ], "operationId": "fatcaGiin", "summary": "FATCA GIIN", "description": "Checks a GIIN against the IRS FATCA Foreign Financial Institution (FFI) list and returns the registered institution name and country.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| found is true and name matches | Accept the GIIN on the W-8BEN-E and keep the request id with the form. |\n| found is true but name differs | The GIIN belongs to another institution. Ask the entity to confirm its GIIN. |\n| found is false | The GIIN is not on the FFI list. Request a corrected W-8BEN-E; without a verified GIIN, FATCA withholding may apply to withholdable payments. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-fatca-giin" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FatcaGiinRequest" }, "example": { "giin": "29SR4B.99999.SL.372" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FatcaGiinResponse" }, "example": { "id": "Gf5hJ7kL9zXc2vB4nM6qW8eR", "request": { "giin": "29SR4B.99999.SL.372", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "fatca-giin" }, "fatcaGiinResult": { "giin": "29SR4B.99999.SL.372", "name": "IBM Ireland Profit Sharing Scheme", "country": "IRELAND", "message": "GIIN match found", "found": true, "completed": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/legal-entity-identifier": { "post": { "tags": [ "International entities" ], "operationId": "legalEntityIdentifier", "summary": "LEI", "description": "Validates a Legal Entity Identifier against the Global LEI Foundation (GLEIF) register and returns the registered entity\u0027s name, address, legal form, jurisdiction and status.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| status is ACTIVE and names match | The LEI is valid for this entity. Save the legal name and address from the record. |\n| status is anything else | The entity is not active in the GLEIF register. Confirm it still exists before relying on it. |\n| No properties returned | The LEI was not found. Check it for typos (20 characters) or ask the entity for its current LEI. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-legal-entity-identifier" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalEntityIdentifierRequest" }, "example": { "lei": "VGRQXHF3J8VDLUA7XE92" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalEntityIdentifierResponse" }, "example": { "id": "Lz4xC6vB8nM0qW2eR4tY6uI8", "request": { "lei": "VGRQXHF3J8VDLUA7XE92", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "legal-entity-identifier" }, "legalEntityIdentifierResult": { "lei": "VGRQXHF3J8VDLUA7XE92", "properties": { "names": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "address": "ONE NORTH CASTLE DRIVE, Armonk, US-NY 10504", "legalform": "Business Corporation", "registrationNumber": "30059", "jurisdiction": "United States", "dateIncorporated": "1911-06-16", "status": "ACTIVE" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/npi-registry": { "post": { "tags": [ "Healthcare \u0026 carriers" ], "operationId": "npiRegistry", "summary": "NPI registry", "description": "Looks up a National Provider Identifier in the CMS NPPES registry and returns its status, the registered provider name, specialty, license and practice address. Send a name as well and the response tells you whether it matches the registry.\n\nPair this endpoint with medicare-enrollment and list-sanctions (which includes the OIG and state exclusion lists) for a complete provider check.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| active is true | The NPI is valid. If you sent a name, check nameMatched before you rely on it. |\n| deactivated is true | Do not credential or pay under this NPI; claims that use it are rejected. Ask the provider for their current NPI. |\n| invalidCheckDigit is true | The number cannot be a real NPI. It was most likely mistyped. |\n| nameMatched is false | The NPI belongs to someone else. Confirm the provider\u0027s identity. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-npi-registry" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NpiRegistryRequest" }, "example": { "npi": "1245319599" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NpiRegistryResponse" }, "example": { "id": "HqG4GysnqkOESU0DgJhQZAUw", "request": { "npi": "1245319599", "requestDate": "2026-10-06T03:03:13Z", "requestedServices": "npi-registry" }, "npiRegistryResult": { "npi": "1245319599", "message": "Active", "found": true, "deactivated": false, "invalidCheckDigit": false, "active": true, "completed": true, "status": "A", "enumerationType": "NPI-1", "isOrganization": false, "name": "TEST PROVIDER", "credential": "M.D.", "soleProprietor": false, "specialty": "Hospitalist", "licenseNumber": "TEST-9001", "licenseState": "MD", "practiceAddress": { "line1": "1 TEST WAY", "city": "BALTIMORE", "state": "MD", "postalCode": "212010000", "countryCode": "US", "telephone": "4105550120" }, "enumerationDate": "2006-05-23T00:00:00", "lastUpdated": "2019-07-08T00:00:00", "retrievedOn": "2026-10-06T03:03:13Z", "industryPayments": [ { "label": "Consulting fees", "transactionCount": 24, "totalAmount": 71350.00 }, { "label": "Food and beverage", "transactionCount": 910, "totalAmount": 36711.18 } ], "industryPaymentsTotal": 150865.17, "industryPaymentsTransactions": 1038 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/medicare-enrollment": { "post": { "tags": [ "Healthcare \u0026 carriers" ], "operationId": "medicareEnrollment", "summary": "Medicare enrollment", "description": "Checks a provider\u0027s Medicare status by NPI: enrolled privileges (Part B, DME, home health, power mobility, hospice), opt-out status with its effective and end dates, and Care Compare profile details.\n\nThe sample shows an opted-out provider. Claims to federal programs for an opted-out provider\u0027s services are not payable, so treat optedOut as a stop for Medicare billing.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| optedOut is true | Do not bill Medicare for this provider\u0027s services between optOutEffectiveDate and optOutEndDate. |\n| found is false and optedOut is false | The provider is not enrolled. Medicare claims that list them will be denied; confirm enrollment before billing. |\n| A privilege (partB, dme, homeHealth, pmd, hospice) is false | The provider cannot order or refer that service type for Medicare patients. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-medicare-enrollment" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicareEnrollmentRequest" }, "example": { "npi": "1245319599" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicareEnrollmentResponse" }, "example": { "id": "jo6nPgXaj0OXUKZMyZCkXgDg", "request": { "npi": "1245319599", "requestDate": "2026-10-06T03:03:13Z", "requestedServices": "medicare-enrollment" }, "medicareEnrollmentResult": { "npi": "1245319599", "message": "Opted out of Medicare", "found": false, "completed": true, "invalidCheckDigit": false, "providerName": "TEST PROVIDER", "optedOut": true, "optOutEffectiveDate": "2022-07-01T00:00:00", "optOutEndDate": "2028-07-01T00:00:00", "optOutSpecialty": "Psychiatry", "careCompare": { "credential": "MD", "medicalSchool": "TEST UNIVERSITY SCHOOL OF MEDICINE", "graduationYear": 2004, "primarySpecialty": "INTERNAL MEDICINE", "telehealth": true, "acceptsAssignment": "Y", "locations": [ { "facilityName": "TEST MEDICAL GROUP", "groupSize": 42, "singleLine": "1 TEST WAY, SUITE 200, BALTIMORE, MD 21201-0000", "phone": "4105550120" } ] }, "partB": false, "dme": false, "homeHealth": false, "pmd": false, "hospice": false, "retrievedOn": "2026-10-06T03:03:13Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate/fmcsa-carrier": { "post": { "tags": [ "Healthcare \u0026 carriers" ], "operationId": "fmcsaCarrier", "summary": "FMCSA carrier", "description": "Looks up a motor carrier by USDOT number and returns whether it is allowed to operate, its operating authority by type (common, contract, broker), insurance filings, out-of-service status and fleet size.\n\nThe sample shows a carrier that is not allowed to operate. A missing insurance filing is not proof a carrier is uninsured, only that no filing is on record with FMCSA.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| allowedToOperate is N | Do not tender loads to this carrier. |\n| oosDate is present | The carrier is under an out-of-service order. Do not dispatch. |\n| The authority you need is not A | The carrier is not authorized to act in that role (common, contract or broker). |\n| bipdInsuranceOnFile is below bipdRequiredAmount | Request a current certificate of insurance before booking. |\n| found is false | Check that you sent the USDOT number, not the MC docket number. |\n| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-fmcsa-carrier" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FmcsaCarrierRequest" }, "example": { "dot": "2213141" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FmcsaCarrierResponse" }, "example": { "id": "qphvFoRev0qje4MyNGc3ywc8", "request": { "dot": "2213141", "requestDate": "2026-10-06T03:03:14Z", "requestedServices": "fmcsa-carrier" }, "fmcsaCarrierResult": { "dot": "2213141", "message": "Not allowed to operate", "found": true, "completed": true, "legalName": "TEST HAULAGE LLC", "allowedToOperate": "N", "statusCode": "I", "commonAuthorityStatus": "I", "contractAuthorityStatus": "N", "brokerAuthorityStatus": "N", "bipdInsuranceRequired": "Y", "bipdRequiredAmount": "750", "totalPowerUnits": 4, "totalDrivers": 4, "carrierOperation": "Interstate", "phyState": "OH", "retrievalDate": "2026-10-06T03:03:14Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/validate": { "post": { "tags": [ "Multi-service" ], "operationId": "validate", "summary": "Validate", "description": "Runs one or more validation services against a single record in one call. Send whatever fields you have; every service those fields support runs, unless you narrow the list with requestedServices.\n\nOnly the result objects for services that ran are included in the response. Each service also has its own endpoint (listed in the navigation) that runs exactly that one service.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| A result object is missing | That service did not run: the fields it needs were not sent, or it is not in requestedServices. Each result object reads the same as on its own endpoint page. |\n| Any result has completed false | Keep the request id and call request-details later. Results that already finished are final; only the pending ones fill in. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-validate" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" }, "example": { "tin": "13-0871985", "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "street": "PO BOX 218", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598", "requestedServices": [ "irs-tin-name-matching", "address-validation", "list-sanctions" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" }, "example": { "id": "ZfPjtFHAXEep29ZZTc5rpgj1", "request": { "tin": "XXXXX1985", "name": "INTERNATIONAL BUSINESS MACHINES CORPORATION", "street": "PO BOX 218", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598", "requestDate": "2026-10-01T14:02:11Z", "requestedServices": "irs-tin-name-matching,address-validation,list-sanctions" }, "irsTinNameMatchingResult": { "message": "TIN and Name combination matches IRS EIN records", "result": 7, "completed": true }, "addressValidationResult": { "street": "218 PO BOX", "city": "YORKTOWN HEIGHTS", "state": "NY", "zip5": "10598", "zip4": "0218", "countyName": "WESTCHESTER", "message": "Address was confirmed as valid", "found": true, "completed": true, "corrections": [ "PO BOX match.", "ZIP\u002B4 corrected." ] }, "listSanctionsMatchResult": { "completed": true, "anyFiltered": false, "results": [ { "name": "INTERNATIONAL BUSINESS MACHINES", "type": "Organization", "confidence": 75, "list": "Business Identifier Code (BIC) Reference Data" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/request-details": { "post": { "tags": [ "Results" ], "operationId": "requestDetails", "summary": "Request details", "description": "Returns the complete stored result of one earlier validation request: the original request and every result object, in the same shape as the validate response. GET with ?id= also works.\n\nReturns 400 when the id is malformed and 404 when no request with that id belongs to your account, both in the url-and-errors format shown on the overview. Requires an API key with the History permission.\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| A result still has completed false | That source has not answered yet. Call request-details again later. |\n| 404 | The id is not on your account. Check that you are using a key for the account that made the request. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-request-details" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDetailsRequest" }, "example": { "id": "BZ5CF5Z2q0SwIBmhZylJggxp" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDetailsResponse" }, "example": { "id": "BZ5CF5Z2q0SwIBmhZylJggxp", "requestedBy": "ERP integration", "request": { "tin": "XXXXX1234", "name": "JOHN SMITH", "requestDate": "2026-10-01T20:23:41Z", "requestedServices": "irs-tin-name-matching" }, "irsTinNameMatchingResult": { "message": "TIN and Name combination does not match IRS records", "result": 3, "completed": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/history": { "post": { "tags": [ "Results" ], "operationId": "history", "summary": "History", "description": "Lists your previous validation requests, newest first, with a summary result for each service.\n\nEach item includes a ResultType field only for the services that ran on that request. requestState: 0 unprocessed, 1 in process, 2 processed, 3 retry, 4 failure.\n\n**Values for the *ResultType fields**\n\n| Value | Meaning |\n|---|---|\n| 0 | Unrequested |\n| 1 | Unprocessed |\n| 2 | Bad |\n| 3 | Good |\n| 4 | Pending |\n| 5 | Indifferent |\n| 6 | Information |\n\n\n**What to do with this result**\n\n| When you see | Do this |\n|---|---|\n| requestState is 0, 1 or 3 | Still working. Call request-details with the item\u0027s id later for the full result. |\n| A ResultType is 2 (Bad) | Call request-details with the item\u0027s id to see exactly what failed. |", "externalDocs": { "url": "https://www.tincomply.com/help-center/api-request-details#history" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryRequest" }, "example": { "page": 1, "count": 20, "search": "acme", "includeApi": true } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" }, "example": { "results": { "page": 1, "count": 20, "total": 143, "lastPage": 8, "direction": "DESC", "items": [ { "id": "BG5CF5Z2q0SwIBmhZylJggxp", "userName": "ERP integration", "customerName": "Acme Widgets Inc", "request": { "name": "ACME WIDGETS INC", "requestedServices": "irs-tin-name-matching,list-sanctions" }, "requestedOn": "2026-10-01T14:02:11Z", "completedOn": "2026-10-01T14:02:12Z", "requestState": 2, "irsResultType": 3, "listResultType": 3 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/status": { "get": { "tags": [ "Service status" ], "operationId": "allServiceStatus", "summary": "Status of every service", "description": "Operating status. Codes: 0 operational, 1 degraded, 2 partial outage, 3 major outage. No API key required.", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "irs-tin-name-matching": { "code": 0, "message": "Operational" }, "list-sanctions": { "code": 0, "message": "Operational" }, "npi-registry": { "code": 0, "message": "Operational" }, "lastUpdated": "2026-10-06T03:03:00Z" } } } } } } }, "/status/{service}": { "get": { "tags": [ "Service status" ], "operationId": "serviceStatus", "summary": "Status of one service", "description": "Operating status. Codes: 0 operational, 1 degraded, 2 partial outage, 3 major outage. No API key required.", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "service", "in": "path", "required": true, "description": "A service identifier, such as irs-tin-name-matching.", "schema": { "type": "string", "enum": [ "irs-tin-name-matching", "company-name-lookup-by-ein", "company-ein-lookup-by-name", "address-validation", "company-details-lookup-by-name-address", "list-sanctions", "fatca-giin", "legal-entity-identifier", "npi-registry", "medicare-enrollment", "fmcsa-carrier" ] } } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "IrsTinNameMatchingRequest": { "type": "object", "properties": { "tin": { "type": "string", "description": "The Taxpayer Identification Number (EIN, SSN or ITIN). 9 digits; hyphens are ignored." }, "name": { "type": "string", "description": "The entity or individual name associated with the TIN." } }, "required": [ "tin", "name" ], "additionalProperties": false }, "IrsTinNameMatchingResult": { "type": "object", "properties": { "result": { "type": "integer", "description": "The IRS result code (see the table below)." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "IrsTinNameMatchingResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "irsTinNameMatchingResult": { "$ref": "#/components/schemas/IrsTinNameMatchingResult" } } }, "CompanyNameLookupByEinRequest": { "type": "object", "properties": { "tin": { "type": "string", "description": "The EIN to look up. 9 digits; hyphens are ignored." } }, "required": [ "tin" ], "additionalProperties": false }, "CompanyNameLookupByEinResult": { "type": "object", "properties": { "name": { "type": "string", "description": "The registered business name." }, "found": { "type": "boolean", "description": "True when a name was found for the EIN." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "CompanyNameLookupByEinResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "companyNameLookupByEinResult": { "$ref": "#/components/schemas/CompanyNameLookupByEinResult" } } }, "CompanyEinLookupByNameRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The company name to search for." } }, "required": [ "name" ], "additionalProperties": false }, "CompanyEinLookupByNameResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" }, "description": "Candidate matches, omitted when there are none. Each item has id, name, ein (masked) and confidence (0 to 100)." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "CompanyEinLookupByNameResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "companyEinLookupByNameResult": { "$ref": "#/components/schemas/CompanyEinLookupByNameResult" } } }, "RevealEinRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the company-ein-lookup-by-name request." }, "resultId": { "type": "string", "description": "The id of the candidate inside companyEinLookupByNameResult.results." } }, "required": [ "id", "resultId" ], "additionalProperties": false }, "RevealEinResponse": { "type": "object" }, "AddressValidationRequest": { "type": "object", "properties": { "street": { "type": "string", "description": "Street address line 1." }, "suite": { "type": "string", "description": "Street address line 2, suite or unit." }, "city": { "type": "string", "description": "City. Required unless zip5 is supplied." }, "state": { "type": "string", "description": "Two-letter state abbreviation." }, "zip5": { "type": "string", "description": "5-digit ZIP code." }, "zip4": { "type": "string", "description": "ZIP\u002B4 extension." }, "address": { "type": "string", "description": "Single-line address, as an alternative to the structured fields." } }, "required": [ "street" ], "additionalProperties": false }, "AddressValidationResult": { "type": "object", "properties": { "street": { "type": "string", "description": "The standardized address." }, "suite": { "type": "string", "description": "The standardized address." }, "city": { "type": "string", "description": "The standardized address." }, "state": { "type": "string", "description": "The standardized address." }, "zip5": { "type": "string", "description": "The standardized address." }, "zip4": { "type": "string", "description": "The standardized address." }, "dpbc": { "type": "string", "description": "Delivery point bar code." }, "congressionalDistrict": { "type": "string", "description": "Congressional district." }, "countyName": { "type": "string", "description": "County." }, "latitude": { "type": "number", "description": "Coordinates, when available." }, "longitude": { "type": "number", "description": "Coordinates, when available." }, "found": { "type": "boolean", "description": "True when USPS confirmed the address." }, "corrections": { "type": "array", "items": { "type": "string" }, "description": "Each change made to the input address." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "AddressValidationResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "addressValidationResult": { "$ref": "#/components/schemas/AddressValidationResult" } } }, "CompanyDetailsLookupByNameAddressRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name." }, "street": { "type": "string", "description": "Address fields." }, "suite": { "type": "string", "description": "Address fields." }, "city": { "type": "string", "description": "Address fields." }, "state": { "type": "string", "description": "Address fields." }, "zip5": { "type": "string", "description": "Address fields." }, "zip4": { "type": "string", "description": "Address fields." }, "address": { "type": "string", "description": "Single-line address, as an alternative to the structured fields." } }, "additionalProperties": false }, "CompanyDetailsLookupByNameAddressResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" }, "description": "Matching companies, omitted when there are none. Each item has name, type, confidence and properties (attribute to value)." }, "anyFiltered": { "type": "boolean", "description": "Always false for this service." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "CompanyDetailsLookupByNameAddressResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "companyDetailsLookupByNameAddressResult": { "$ref": "#/components/schemas/CompanyDetailsLookupByNameAddressResult" } } }, "ListSanctionsRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The person or business name to screen." } }, "required": [ "name" ], "additionalProperties": false }, "ListSanctionsMatchResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" }, "description": "Hits, omitted when there are none. Each item has name, type, confidence, list (the source list), properties, related and relationships." }, "anyFiltered": { "type": "boolean", "description": "True when the name matched an entry that appears only on lists your account does not have enabled. Those hits are left out of results." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "ListSanctionsResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "listSanctionsMatchResult": { "$ref": "#/components/schemas/ListSanctionsMatchResult" } } }, "FatcaGiinRequest": { "type": "object", "properties": { "giin": { "type": "string", "description": "The 19-character GIIN, including the dots." } }, "required": [ "giin" ], "additionalProperties": false }, "FatcaGiinResult": { "type": "object", "properties": { "giin": { "type": "string", "description": "The GIIN checked." }, "name": { "type": "string", "description": "Registered institution name." }, "country": { "type": "string", "description": "Registered country." }, "found": { "type": "boolean", "description": "True when the GIIN is on the FFI list." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "FatcaGiinResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "fatcaGiinResult": { "$ref": "#/components/schemas/FatcaGiinResult" } } }, "LegalEntityIdentifierRequest": { "type": "object", "properties": { "lei": { "type": "string", "description": "The 20-character LEI." } }, "required": [ "lei" ], "additionalProperties": false }, "LegalEntityIdentifierResult": { "type": "object", "properties": { "lei": { "type": "string", "description": "The LEI checked." }, "properties": { "type": "object", "description": "Attributes from the GLEIF record: names, address, legalform, registrationNumber, jurisdiction, dateIncorporated, status and more." } }, "description": "Present when this service ran." }, "LegalEntityIdentifierResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "legalEntityIdentifierResult": { "$ref": "#/components/schemas/LegalEntityIdentifierResult" } } }, "NpiRegistryRequest": { "type": "object", "properties": { "npi": { "type": "string", "description": "The 10-digit NPI." }, "name": { "type": "string", "description": "Optional. The provider name on your record, compared against the registry name." } }, "required": [ "npi" ], "additionalProperties": false }, "NpiRegistryResult": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Registry status of the NPI." }, "active": { "type": "boolean", "description": "Registry status of the NPI." }, "deactivated": { "type": "boolean", "description": "Registry status of the NPI." }, "invalidCheckDigit": { "type": "boolean", "description": "True when the NPI fails its check-digit test and cannot be valid." }, "status": { "type": "string", "description": "Registry status code and NPI type (NPI-1 individual, NPI-2 organization)." }, "enumerationType": { "type": "string", "description": "Registry status code and NPI type (NPI-1 individual, NPI-2 organization)." }, "isOrganization": { "type": "boolean", "description": "Provider type flags." }, "soleProprietor": { "type": "boolean", "description": "Provider type flags." }, "name": { "type": "string", "description": "Registered provider name and credential." }, "credential": { "type": "string", "description": "Registered provider name and credential." }, "authorizedOfficialName": { "type": "string", "description": "Authorized official, for organizations." }, "authorizedOfficialTitle": { "type": "string", "description": "Authorized official, for organizations." }, "specialty": { "type": "string", "description": "Primary taxonomy and license." }, "licenseNumber": { "type": "string", "description": "Primary taxonomy and license." }, "licenseState": { "type": "string", "description": "Primary taxonomy and license." }, "practiceAddress": { "type": "object", "description": "line1, city, state, postalCode, countryCode, telephone." }, "mailingAddress": { "type": "object", "description": "line1, city, state, postalCode, countryCode, telephone." }, "enumerationDate": { "type": "string", "format": "date-time", "description": "Registry dates and when we retrieved the record." }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Registry dates and when we retrieved the record." }, "retrievedOn": { "type": "string", "format": "date-time", "description": "Registry dates and when we retrieved the record." }, "submittedName": { "description": "Comparison against the name you sent, when you sent one." }, "nameMatched": { "description": "Comparison against the name you sent, when you sent one." }, "nameMatchScore": { "description": "Comparison against the name you sent, when you sent one." }, "industryPayments": { "type": "array", "items": { "type": "object" }, "description": "CMS Open Payments summary by category: label, transactionCount, totalAmount." }, "industryPaymentsTotal": { "type": "number", "description": "Open Payments totals." }, "industryPaymentsTransactions": { "type": "number", "description": "Open Payments totals." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "NpiRegistryResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "npiRegistryResult": { "$ref": "#/components/schemas/NpiRegistryResult" } } }, "MedicareEnrollmentRequest": { "type": "object", "properties": { "npi": { "type": "string", "description": "The 10-digit NPI." } }, "required": [ "npi" ], "additionalProperties": false }, "MedicareEnrollmentResult": { "type": "object", "properties": { "found": { "type": "boolean", "description": "True when the NPI is enrolled in Medicare." }, "invalidCheckDigit": { "type": "boolean", "description": "True when the NPI fails its check-digit test." }, "providerName": { "type": "string", "description": "Provider name on the Medicare record." }, "optedOut": { "type": "boolean", "description": "True when the provider has opted out of Medicare." }, "optOutEffectiveDate": { "type": "string", "format": "date-time", "description": "Opt-out period." }, "optOutEndDate": { "type": "string", "format": "date-time", "description": "Opt-out period." }, "optOutSpecialty": { "type": "string", "description": "Specialty on the opt-out affidavit." }, "partB": { "type": "boolean", "description": "Enrolled Medicare privileges." }, "dme": { "type": "boolean", "description": "Enrolled Medicare privileges." }, "homeHealth": { "type": "boolean", "description": "Enrolled Medicare privileges." }, "pmd": { "type": "boolean", "description": "Enrolled Medicare privileges." }, "hospice": { "type": "boolean", "description": "Enrolled Medicare privileges." }, "careCompare": { "type": "object", "description": "credential, medicalSchool, graduationYear, primarySpecialty, secondarySpecialties, telehealth, acceptsAssignment and locations." }, "retrievedOn": { "type": "string", "format": "date-time", "description": "When we retrieved the record." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "MedicareEnrollmentResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "medicareEnrollmentResult": { "$ref": "#/components/schemas/MedicareEnrollmentResult" } } }, "FmcsaCarrierRequest": { "type": "object", "properties": { "dot": { "type": "string", "description": "The USDOT number. Not an MC docket number." } }, "required": [ "dot" ], "additionalProperties": false }, "FmcsaCarrierResult": { "type": "object", "properties": { "found": { "type": "boolean", "description": "True when the USDOT number exists." }, "legalName": { "type": "string", "description": "Registered legal and DBA names." }, "dbaName": { "type": "string", "description": "Registered legal and DBA names." }, "allowedToOperate": { "type": "string", "description": "FMCSA operating status (Y or N) and status code." }, "statusCode": { "type": "string", "description": "FMCSA operating status (Y or N) and status code." }, "commonAuthorityStatus": { "type": "string", "description": "Operating authority by type: A active, I inactive, N none." }, "contractAuthorityStatus": { "type": "string", "description": "Operating authority by type: A active, I inactive, N none." }, "brokerAuthorityStatus": { "type": "string", "description": "Operating authority by type: A active, I inactive, N none." }, "bipdInsuranceOnFile": { "type": "string", "description": "Liability (BIPD) insurance filing and requirement, in thousands of dollars." }, "bipdInsuranceRequired": { "type": "string", "description": "Liability (BIPD) insurance filing and requirement, in thousands of dollars." }, "bipdRequiredAmount": { "type": "string", "description": "Liability (BIPD) insurance filing and requirement, in thousands of dollars." }, "cargoInsuranceOnFile": { "type": "string", "description": "Cargo insurance and broker bond filings." }, "bondInsuranceOnFile": { "type": "string", "description": "Cargo insurance and broker bond filings." }, "oosDate": { "type": "string", "format": "date-time", "description": "Out-of-service order date. Present only when the carrier is under an out-of-service order." }, "totalPowerUnits": { "type": "integer", "description": "Fleet size." }, "totalDrivers": { "type": "integer", "description": "Fleet size." }, "safetyRating": { "type": "string", "description": "Safety rating, operation type and physical state." }, "carrierOperation": { "type": "string", "description": "Safety rating, operation type and physical state." }, "phyState": { "type": "string", "description": "Safety rating, operation type and physical state." }, "retrievalDate": { "type": "string", "format": "date-time", "description": "When we retrieved the record." }, "message": { "type": "string", "description": "Human-readable summary of the result." }, "completed": { "type": "boolean", "description": "False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result." } }, "description": "Present when this service ran." }, "FmcsaCarrierResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "fmcsaCarrierResult": { "$ref": "#/components/schemas/FmcsaCarrierResult" } } }, "ValidateRequest": { "type": "object", "properties": { "tin": { "type": "string", "description": "Taxpayer Identification Number (EIN, SSN or ITIN). 9 digits; hyphens are ignored." }, "name": { "type": "string", "description": "Legal name of the entity or individual, as it should appear in IRS records." }, "street": { "type": "string", "description": "Street address line 1." }, "suite": { "type": "string", "description": "Street address line 2, suite or unit." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "Two-letter state abbreviation." }, "zip5": { "type": "string", "description": "5-digit ZIP code." }, "zip4": { "type": "string", "description": "ZIP\u002B4 extension." }, "address": { "type": "string", "description": "Single-line address, as an alternative to the structured fields." }, "giin": { "type": "string", "description": "FATCA Global Intermediary Identification Number (19 characters with dots)." }, "lei": { "type": "string", "description": "Legal Entity Identifier (20 characters)." }, "npi": { "type": "string", "description": "10-digit National Provider Identifier." }, "dot": { "type": "string", "description": "USDOT number (not an MC docket number)." }, "requestedServices": { "type": "array", "items": { "type": "string", "enum": [ "irs-tin-name-matching", "company-name-lookup-by-ein", "company-ein-lookup-by-name", "address-validation", "company-details-lookup-by-name-address", "list-sanctions", "fatca-giin", "legal-entity-identifier", "npi-registry", "medicare-enrollment", "fmcsa-carrier" ] }, "description": "Service identifiers to run (see the list below). Omit to run every service enabled on your account that the supplied fields allow." } }, "additionalProperties": false }, "ValidateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Request id. Use it with request-details." }, "request": { "type": "object", "description": "The request as received, with the TIN masked." }, "irsTinNameMatchingResult": { "$ref": "#/components/schemas/IrsTinNameMatchingResult" }, "companyNameLookupByEinResult": { "$ref": "#/components/schemas/CompanyNameLookupByEinResult" }, "companyEinLookupByNameResult": { "$ref": "#/components/schemas/CompanyEinLookupByNameResult" }, "addressValidationResult": { "$ref": "#/components/schemas/AddressValidationResult" }, "companyDetailsLookupByNameAddressResult": { "$ref": "#/components/schemas/CompanyDetailsLookupByNameAddressResult" }, "listSanctionsMatchResult": { "$ref": "#/components/schemas/ListSanctionsMatchResult" }, "fatcaGiinResult": { "$ref": "#/components/schemas/FatcaGiinResult" }, "legalEntityIdentifierResult": { "$ref": "#/components/schemas/LegalEntityIdentifierResult" }, "npiRegistryResult": { "$ref": "#/components/schemas/NpiRegistryResult" }, "medicareEnrollmentResult": { "$ref": "#/components/schemas/MedicareEnrollmentResult" }, "fmcsaCarrierResult": { "$ref": "#/components/schemas/FmcsaCarrierResult" } } }, "RequestDetailsRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "The request id returned by a validate call." } }, "required": [ "id" ], "additionalProperties": false }, "RequestDetailsResponse": { "type": "object" }, "HistoryRequest": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page number, starting at 1." }, "count": { "type": "integer", "description": "Page size." }, "search": { "type": "string", "description": "Optional free-text filter, such as a name or TIN fragment." }, "includeApi": { "type": "boolean", "description": "Include requests made with API keys, not only portal requests." } }, "additionalProperties": false }, "HistoryResponse": { "type": "object" }, "ValidationErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "ErrorMessage": { "type": "object", "properties": { "message": { "type": "string" } } }, "NotFoundError": { "type": "object", "properties": { "url": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "BadRequest": { "description": "The request could not be processed. The body is keyed by field name, each listing what was wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrors" }, "example": { "foo": [ "The key foo is not a valid key for the request object." ], "tin": [ "TIN is invalid." ] } } } }, "Unauthorized": { "description": "The API key is missing, not recognized, or lacks the permission this endpoint requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Invalid API Key" } } } }, "NotFound": { "description": "No request with that id belongs to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "example": { "url": "/api/v1/request-details", "errors": [ "The id provided could not be found" ] } } } } } } }