[Archived - SDK v1.x] Decisioning Based on Tax Documentation Status

You may want to consider the following before loading the tax documentation collection form:

• If the customer has filled out the tax collection form in a previous session, and the system has validated their data, you may not want to show the form again.
• As described in Editing Tax Documentation, there are a few cases where a customer may need to edit or re-certify data. For example, if the IRS notifies TaxBit that the customer's name or tax ID is invalid, you should show the form again so your customer can correct their information.

The Tax Documentation Status object will provide the necessary information for you to take appropriate action. Therefore, you should request the Tax Documentation Status of the customer before attempting to load the form.

Retrieving the tax documentation status

Retrieve the tax documentation status as follows:

const documentationStatus = await taxBit.rest.taxDocumentation.status.get();

Even if you still need to collect tax documentation for your customer, this code will always provide you with a status object.

Status

The status object you'll receive has the following properties:

documentType: string

This field contains the government-issued document used to collect tax documentation for the customer, if any. The possible values for this field are:

• UNDETERMINED (default): The system has yet to determine the document type based on the information TaxBit currently has, if any, for the customer.
• W9: The system has determined that the customer qualifies for a W9 tax form.
• UNKNOWN: This value is a catch-all for any values TaxBit may add later. If TaxBit adds a new document type, we will publish a new version of the SDK that will return the new value instead of UNKNOWN. When we release a new SDK with new document types, we will encourage you to upgrade to the latest version of the SDK and properly adjust any logic you may have which uses these documentType values.

issues: object[] | undefined

This field contains an array of tax documentation issue objects representing any current issues with the tax documentation you have collected (see the Tax Documentation Issue section below). This field will be undefined if no problems exist.

status: string

This field contains the current status of the tax documentation.

Possible values:

• DOCUMENTED: This status means that the customer has completed the collection form, made all necessary changes, and has certified their data. This status does not mean the customer's tax documentation is free from issues. After the customer certifies their tax documentation, TaxBit asynchronously validates some of the tax documentation, like the customer's name and tax ID, with the IRS. The system will include any issues the IRS indicates within the issues array.
• UNDOCUMENTED: This status means that the customer has completed the collection form, made all necessary changes, and has certified their data. However, you have ingested data into TaxBit for the customer through other means. We will set the status of this field to UNDOCUMENTED until the customer certifies your ingested data.
• UNKNOWN: This status is a catch-all for any values TaxBit may add later. If TaxBit adds a new status type, we will release a new version of the SDK that returns the new value instead of UNKNOWN. We will then encourage you to upgrade to the latest version of the SDK and properly adjust any logic you may have which uses these status values.

tinValidationStatus: string | undefined

This field contains the status of validating the tax ID with the IRS. We validate the customer's tax ID after the customer completes the collection form. This field will be undefined if the documentType is not W9.

Possible values:

• INVALID: TaxBit sent the tax ID information to the IRS, and the IRS has indicated that the tax ID is invalid.
• MISMATCH: TaxBit sent the tax ID information to the IRS, and the IRS has indicated that the name and tax ID combination do not match their records.
• NOT_ISSUED: TaxBit sent the tax ID information to the IRS, and the IRS has indicated that they have yet to issue the tax ID.
• PENDING: TaxBit sent the tax ID information to the IRS, but the IRS still needs to respond.
• UNPROCESSED: TaxBit still needs to send the tax ID information to the IRS for validation.
• VALID: TaxBit sent the tax ID information to the IRS, and the IRS has indicated the name and tax ID combination match their records.
• VALID_TIN_TYPE_MISMATCH: TaxBit has sent the tax ID information to the IRS, and the IRS has stated the tax ID is valid but does not match the tax ID type the customer provided.
• UNKNOWN: This status is a catch-all for any values TaxBit may add later. If TaxBit adds a new value, we will release a new version of the SDK that returns the new value instead of UNKNOWN. At that point, we will encourage you to upgrade to the latest version of the SDK and properly adjust any logic you may have which uses these values.

Tax documentation issue

As described above, we will return a Tax Documentation Issue object, one per issue we find in the customer's tax documentation. Each Tax Documentation Issue object has the following properties:

type: string

Issues may have one of the following type values:

• TIN_VALIDATION_FAILURE: We have sent the tax ID information to the IRS, and the IRS has indicated that it is invalid.
• INCOMPLETE: TaxBit has received some tax documentation for the customer, but the customer still needs to complete the collection form, make any necessary changes, and certify their data.
• NO_DATA: TaxBit has not received any tax documentation for the customer.
• UNKNOWN: This type is a catch-all for any values TaxBit may add later. If TaxBit adds a new value, we will release a new version of the SDK that returns the new value instead of UNKNOWN. At that point, we will encourage you to upgrade to the latest version of the SDK and properly adjust any logic you may have which uses these values.

Typical decisioning logic

To handle the scenarios described above, you'll first request the tax documentation status for your customer, then execute logic similar to the following based on your needs:

• If you receive a DOCUMENTED status, you've already sent the user through the collection form, and they have successfully certified and submitted their tax documentation.
  • If there are issues with the documentation the user submitted, load the edit form.
  • If there are no issues with the documentation the user submitted, congratulations! You've received valid certified documentation. You do not need to show any form for the user.
• You have yet to send the user through the collection form if your status is something other than DOCUMENTED. For example, you may have sent some of the customer's tax documentation to TaxBit servers through a separate ingestion process. Whatever the case, you still need your customer to complete and certify their documentation.
  • If you still need to collect data for the customer, load the create form.
  • If you have sent at least some data to the TaxBit servers for the customer, you will need the customer to complete and certify their documentation, so load the edit form.

Here is an example of how you might implement this logic in code:

const documentationStatus = await taxBit.rest.taxDocumentation.status.get(); 

if (documentationStatus.status === "DOCUMENTED") {
  if (documentationStatus.issues) {
    taxBit.ui.taxDocumentation.loadEditForm({
      hostElement: myContainer
    });
  } else {
    // Tax documentation is complete without issues!
  }
} else if (documentationStatus.status === "UNDOCUMENTED") {
  if (documentationStatus.issues?.some(issue => issue.type === "NO_DATA")) {
    taxBit.ui.taxDocumentation.loadCreateForm({
      hostElement: myContainer,
      documentType: "W9",
      data: {
        name: "Pat Sanderson"
      }
    });
  } else {
    taxBit.ui.taxDocumentation.loadEditForm({
      hostElement: myContainer
    });
  }
}