This endpoint allows you to validate a given name and TIN against the IRS. If the validation cannot be performed immediately (due to rate limits or IRS unavailability), the request is enqueued for asynchronous processing.

Endpoint

Path: /v1/validation/us-tin
Method: POST
Authentication: Tenant-Scoped Token

Query Parameters

• use_async (boolean, defaults false): If true, the endpoint will immediately respond back with a status of pending and an identifier to retrieve the result. This is useful for avoiding the latency introduced by the IRS.

Request Body

The request body should be a JSON object containing the following fields:

{  
  "legal_name": "John Doe",  
  "tin": "987654321"  
}

• legal_name (string, required): The full legal name of the individual or entity. Cannot be an empty string.
• tin (string, required): The Tax Identification Number for the individual or entity. Must be a string containing 9 digits with no hyphens, symbols, or punctuation.

Response Body

The response body will be a JSON object containing the following fields:

{  
  "id": "6e9666c7-5ae9-47d7-8e0e-cdca1132e259",  
  "legal_name": "John Doe",  
  "tin": "987654321"  
  "status": "MATCHED",  
  "validation_date": "2024-04-20T04:04:21.000Z"  
}

• id (string, required): The generated id that represents the real time TIN request. In an asynchronous scenario, this is used to retrieve the result.
• legal_name (string, required): The name provided by the client.
• tin (string, required): The TIN provided by the client.
• status (string, required): The validation result from the IRS. If the request has to be made asynchronously then this will be PENDING. Possible values include:
  • PENDING
  • FOREIGN
  • INVALID_DATA
  • VALID_SSN_MATCH
  • VALID_EIN_MATCH
  • VALID_SSN_EIN_MATCH
  • MISMATCH
  • TIN_NOT_ISSUED
  • ERROR
• validation_date (string, optional): The date that the validation was made against the IRS.

Asynchronous Result Retrieval

If the request could not be made synchronously or the use_async query param was set to true, then the RTTM endpoint will return a response of:

{  
  "id": "6e9666c7-5ae9-47d7-8e0e-cdca1132e259",  
  "legal_name": "John Doe",  
  "tin": "987654321"  
  "status": "PENDING",  
}

In this case, there are two options for receiving the results.

Polling

You can make a GET request using the id pulled from the response body.
Path: /v1/validations/us-tin/{tin_validation_id}
Method: GET
Authentication: Tenant-Scoped Token

This will return a response with the same shape as the POST. If the status is still pending, then you will need to continue polling.

Webhook

If you have webhooks configured, then once a request has been processed, a notification will be sent via webhook:

{  
    "id": "6e9666c7-5ae9-47d7-8e0e-cdca1132e259",  
    "event_type": "RTTM_TIN_VERIFICATION",  
    "status": "MATCHED",  
    "validation_date": "2024-03-01T10:00:00.000Z"  
}

Usage Rules

The IRS imposes restrictions around duplicate requests to prevent bad actors from phishing for personal information. As such, we allow for up to 4 duplicate requests to be made within a 24 hour period. The following are the rules for what is considered to be a duplicate request:

1. A request containing the same name as a previously submitted request
   1. Example: { “legal_name”: “Jon Smith”, “tin”: “569385356” } and { “legal_name”: ”Jon Smith”, ”tin”: ”123456789” }.
2. A request containing the same TIN as a previously submitted request
   1. Example: { ”legal_name”: ”Jack Ryan”, ”tin”: ”569385356” } and { ”legal_name”: ”Jon Smith”, ”tin”: ”569385356” }.

If the limit is reached, all subsequent duplicate requests will enter the asynchronous flow and receive a status of PENDING.

For requests that are an exact match with the same name and TIN value, TaxBit will cache the response from the IRS for up to 24 hours so that exact matches do not count against the duplicate request limit. TaxBit will respond to these exact match requests with the cached result.