Skip to main content

How Does BOI Reporting with TaxBandits API Work? The Complete Workflow

· 9 min read
TaxBandits Tech

Under the Corporate Transparency Act, FinCEN requires many small businesses established or registered in the U.S. to report details about their beneficial owners, starting in 2024. This law was enacted to prevent money laundering and enhance financial transparency.

Our API provides you with a simplified way to automate BOI reporting for your clients right from your existing systems, ensuring FinCEN compliance while reducing the manual processes involved. We support all types of BOI reports – Initial, Update, Correction, and Newly Exempt Entity.

In this blog, we'll guide you on how to use our BOIR API to automate the BOI reporting process.

1. Preliminary Steps​

Before initiating BOIR automation, you must complete the following steps.

  • Webhook Configuration (Optional) - TaxBandits API allows you to receive status updates regarding your BOI reports via webhooks. For that, you must configure webhooks for the event type ‘BOI Report Status Change’. For detailed information, click here.

  • OAuth 2.0 Authentication - This is a common step for every endpoint. Before using any endpoint, you must get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. For detailed information, click here.

{
    "alg": "HS256", /*Algorithm = HS256*/
    "typ": "JWT" /*Type = JSON Web Token (JWT)*/
}

Payload:​

{
    "iss": "968a9c78dae29a29",  /*Issuer: Client ID retrieved from the console site*/
    "sub": "968a9c78dae29a29",  /*Subject: Client ID retrieved from the console site*/
    "aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token retrieved from the console site*/
    "iat": 1516239022 /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
}

Signature:​

 HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg  /*Client Secret retrieved from the console site*/
)

Sample JWS:​

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxM
TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

OAuth server will receive the JWS & will validate to provide the JWT (Access token) in the following response format:

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3Rlc3RvYXV0aC5leHByZXNzYXV0aC5uZXQvdjIvIiwic3ViIjoiOWYzZTQwM2RlMWQ5YTNkMiIsImF1ZCI6ImNhNjRkNzMyMzBhNDRkMjY4MjkzN2I2ODQ0ZmJjNTI4IiwiaWF0IjoxNjk0NTg1NDU4LCJleHAiOjE2OTQ1ODkwNTh9.WPOCs-lxo3GXz7_zGGmQovWZy4WD0smW7n-U-InuoME",
    "TokenType": "Bearer",
    "ExpiresIn": 3600,
    "Errors": null
}

2. Report Generation​

To generate the BOI report for a reporting company, you can call the BOIR/Create endpoint. The request JSON must include the report type and the necessary information about the reporting company, beneficial owners, and company applicants.

For example, if you want to create an initial BOI report for a company, you must set the 'ReturnType' as 'INITIAL' and include the necessary reporting information. For other types of reports, you can specify the 'ReturnType' as 'UPDATE', 'CORRECT', or 'EXEMPT' accordingly.

Request:​

{
"ReturnHeader": {
    "ReportType": "INITIAL",
    "IsRequestFinCENId": false,
    "PrevReportDetails": {
        "SubmissionId": null,
        "LegalNm": null,
        "TINType": null,
        "TIN": null,
        "TaxIDCountry": null
    },
    "ReportingCompany": {
        "ReportingCompanyId": null,
        "TINType": "EIN",
        "TIN": "349756386",
        "LegalNm": "Snowdaze LLC",
        "DBAs": [
            "Iceberg Icecreams"
        ],
        "TaxIDCountry": null,
        "FormationInformation": {
            "IsCompanyFormedBefore2024": false,
            "CountryOfFormation": "US",
            "DomesticReportingCompany": {
                "FormedState": "AL",
                "FormedTribalJurisdiction": null,
                "OtherTribeNm": null
            },
            "ForeignReportingCompany": {
                "FirstRegisteredState": null,
                "FirstRegisteredTribalJurisdiction": null,
                "OtherTribeNm": null
            }
        },
        "USAddress": {
            "StreetAddress": "3576 AIRPORT WAY",
            "City": "FAIRBANKS",
            "State": "AK",
            "ZipCd": "99709"
        },
        "IsForeignPooled": false
    }
},
"ReturnData": {
    "CompanyApplicants": [
        {
            "SequenceId": "1",
            "CompanyApplicantId": null,
            "FinCENID": null,
            "FirstNm": "Shawn",
            "MiddleNm": null,
            "LastNm": "Williams",
            "Suffix": null,
            "DOB": "01/28/1999",
            "AddressType": "Residential",
            "Address": {
                "StreetAddress": "120 Bremner Blvd",
                "City": "Toronto",
                "State": "ON",
                "ZipCd": "AB4 568",
                "Country": "CA"
            },
            "FormOfIdentification": {
                "DocumentType": "Driving_License",
                "DocumentNumber": "340007237",
                "ForeignDocumentCountry": "US",
                "DocumentIssuedState": "AK",
                "DocumentIssuedLocalOrTribal": null,
                "OtherLocalOrTribal": null
            }
        }
    ],
    "BeneficialOwners": [
        {
            "SequenceId": "1",
            "BeneficialOwnerId": null,
            "IsParentOrGuardian": false,
            "FinCENID": null,
            "IsExemptEntity": false,
            "ExemptEntityInformation": {
                "EntityLegalNm": null,
                "IndividualLastNm": null
            },
            "FirstNm": "Chandler",
            "MiddleNm": null,
            "LastNm": "Smith",
            "LegalNm": null,
            "Suffix": null,
            "DOB": "01/28/1999",
            "ResidentialAddress": {
                "StreetAddress": "120 Bremner Blvd",
                "City": "Toronto",
                "State": "ON",
                "ZipCd": "AB4 568",
                "Country": "CA"
            },
            "FormOfIdentification": {
                "DocumentType": "Driving_License",
                "DocumentNumber": "340007237",
                "ForeignDocumentCountry": "US",
                "DocumentIssuedState": "AL",
                "DocumentIssuedLocalOrTribal": null,
                "OtherLocalOrTribal": null
            }
        }
    ],
    "SubmitterInformation": {
        "FirstNm": "James",
        "LastNm": "Smith",
        "Email": "james@sample.com"
    }
}
}

Note: To edit the information in the BOI report you created, you can use the 'BOIR/Edit' endpoint. Please note that you can edit the BOI reports are transmitted.

3. Upload Attachment​

For each beneficial owner and company applicant you’ve included in your report, you must attach an identifying document such as a non-expired U.S. driver's license, a non-expired identification document issued by a U.S. state or local government or Indian Tribe, a non-expired U.S. passport, or a non-expired passport issued by a foreign government.

Once your BOI report is created, you can call the BOIR/AttachDocuments endpoint to upload the identifying documents as PDFByte or FilePath for a 'CompanyApplicantId' or 'BeneficialOwnerId'. When uploading an attachment using FilePath, ensure the file is downloadable. You can submit up to 100 MB (cumulative of all attachment file Byte Arrays) or 100 documents per submission, with each Byte Array having a maximum size of 4 MB. If you upload multiple documents for a single ID, the most recent document will be updated.

Note: Ensure to upload documents as PDFByte or FilePath and not both.

Request:​

{
"CompanyApplicantAttachments": [
    {
    "CompanyApplicantId": "251622d2-2ec8-4b19-aa68-c17c7feeb99f",
    "PDFByte": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoRm9ybSAxMDk5IExU==",
    "FilePath": null
    }
],
"BeneficialOwnerAttachments": [
    {
    "BeneficialOwnerId": "7ff5b4aa-e4cb-403f-9405-209a71b4f69e",
    "PDFByte": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoRm9ybSAxMDk5IEg==",
    "FilePath": null
    }
]
}

Note: To view the identifying documents attached to your BOI reports, you can use the 'BOIR/ViewAttachment' endpoint. The request must include the BeneficialOwnerIds and/or CompanyApplicantIds.

4. Transmit Report​

Once your report is completed, you can call the BOIR/Transmit endpoint to transmit the report to FinCEN. Note that after transmitting the report, it cannot be edited or deleted.

Request:​

{
    "SubmissionId": "e081f20f-6f4f-4984-a369-bf409cc59a8a",
    "ReportNumber": null
}

5. Retrieve Status​

If you have configured webhooks for 'BOI Report Status Change', as mentioned earlier, you'll automatically receive status notifications regarding the status of your submitted BOI reports. If not, you can use the 'BOIR/Status' endpoint to retrieve the status of a BOI report you transmitted.

The response will include the statuses listed below,

  • Created: BOIR has been created and has not yet been transmitted by the user.
  • Transmitted: BOIR has been transmitted by the user.
  • Accepted: BOIR is accepted by the FinCEN.
  • Rejected: BOIR is rejected by the FinCEN due to some errors. Please correct the errors and retransmit them.

Request:​

BOIR/Status?SubmissionId=954cdad5-3b8a-4123-9052-8beba4be5376

Rejection Handling​

If the FinCEN has rejected your BOI report due to any errors, you can fix them and retransmit the report. To do so, you can use the 'BOIR/Edit' endpoint to make changes based on the rejection reason and resubmit it to FinCEN.

Request:​

{
    "ReturnHeader": {
        "SubmissionId": "fadae687-8036-4343-bcdc-e5d41dc4a1b6",
        "ReportNumber": null,
        "ReportType": "INITIAL",
        "PrevReportDetails": {
            "SubmissionId": null,
            "LegalNm": null,
            "TINType": null,
            "TIN": null,
            "TaxIDCountry": null
        },
        "IsRequestFinCENId": false,
        "ReportingCompany": {
            "ReportingCompanyId": "db713b7d-5459-4765-9ec8-5ec27d5ff2f4",
            "TINType": "EIN",
            "TIN": "349756316",
            "LegalNm": "Snowdaze LLC",
            "DBAs": [
                "Iceberg Icecreams"
            ],
            "TaxIDCountry": null,
            "FormationInformation": {
                "IsCompanyFormedBefore2024": false,
                "CountryOfFormation": "US",
                "DomesticReportingCompany": {
                    "FormedState": "AL",
                    "FormedTribalJurisdiction": null,
                    "OtherTribeNm": null
                },
                "ForeignReportingCompany": {
                    "FirstRegisteredState": null,
                    "FirstRegisteredTribalJurisdiction": null,
                    "OtherTribeNm": null
                }
            },
            "USAddress": {
                "StreetAddress": "3576 AIRPORT WAY",
                "City": "FAIRBANKS",
                "State": "AK",
                "ZipCd": "99709"
            },
            "IsForeignPooled": false
        }
    },
    "ReturnData": {
        "AddCompanyApplicants": [
            {
                "SequenceId": "1",
                "CompanyApplicantId": null,
                "FinCENID": null,
                "FirstNm": "Shawn",
                "MiddleNm": null,
                "LastNm": "Williams",
                "Suffix": null,
                "DOB": "01/28/1999",
                "AddressType": "Residential",
                "Address": {
                    "StreetAddress": "120 Bremner Blvd",
                    "City": "Toronto",
                    "State": "ON",
                    "ZipCd": "AB4 568",
                    "Country": "CA"
                },
                "FormOfIdentification": {
                    "DocumentType": "Driving_License",
                    "DocumentNumber": "340007237",
                    "ForeignDocumentCountry": "US",
                    "DocumentIssuedState": "AK",
                    "DocumentIssuedLocalOrTribal": null,
                    "OtherLocalOrTribal": null
                }
            }
        ],
        "EditCompanyApplicants": [
            {
                "SequenceId": "1",
                "CompanyApplicantId": "a14292c9-fb21-40a3-b34a-791db876a84e",
                "FinCENID": null,
                "FirstNm": "Chandler",
                "MiddleNm": null,
                "LastNm": "Williams",
                "Suffix": null,
                "DOB": "01/28/1999",
                "AddressType": "Residential",
                "Address": {
                    "StreetAddress": "120 Bremner Blvd",
                    "City": "Toronto",
                    "State": "ON",
                    "ZipCd": "AB4 568",
                    "Country": "CA"
                },
                "FormOfIdentification": {
                    "DocumentType": "Driving_License",
                    "DocumentNumber": "340007237",
                    "ForeignDocumentCountry": "US",
                    "DocumentIssuedState": "AK",
                    "DocumentIssuedLocalOrTribal": null,
                    "OtherLocalOrTribal": null
                }
            }
        ],
        "DeleteCompanyApplicants": [
            {
                "CompanyApplicantId": "d7f514ee-b00e-4755-a0d4-0755e693ce60"
            }
        ],
        "AddBeneficialOwners": [
            {
                "SequenceId": "1",
                "BeneficialOwnerId": null,
                "IsParentOrGuardian": false,
                "FinCENID": null,
                "LegalNm":null,
                "IsExemptEntity": false,
                "ExemptEntityInformation": {
                    "EntityLegalNm": null,
                    "IndividualLastNm": null
                },
                "FirstNm": "Peter",
                "MiddleNm": null,
                "LastNm": "Paul",
                "Suffix": null,
                "DOB": "01/28/1999",
                "ResidentialAddress": {
                    "StreetAddress": "120 Bremner Blvd",
                    "City": "Toronto",
                    "State": "ON",
                    "ZipCd": "AB4 568",
                    "Country": "CA"
                },
                "FormOfIdentification": {
                    "DocumentType": "Driving_License",
                    "DocumentNumber": "340007237",
                    "ForeignDocumentCountry": "US",
                    "DocumentIssuedState": "AL",
                    "DocumentIssuedLocalOrTribal": null,
                    "OtherLocalOrTribal": null
                }
            }
        ],
        "EditBeneficialOwners": [
            {
                "SequenceId": "1",
                "BeneficialOwnerId": "3fecd7b7-d19b-4891-87c7-5434bbdcc086",
                "IsParentOrGuardian": false,
                "FinCENID": null,
                "LegalNm":null,
                "IsExemptEntity": false,
                "ExemptEntityInformation": {
                    "EntityLegalNm": null,
                    "IndividualLastNm": null
                },
                "FirstNm": "Chandler",
                "MiddleNm": null,
                "LastNm": "Smith",
                "Suffix": null,
                "DOB": "01/28/1999",
                "ResidentialAddress": {
                    "StreetAddress": "120 Bremner Blvd",
                    "City": "Toronto",
                    "State": "ON",
                    "ZipCd": "AB4 568",
                    "Country": "CA"
                },
                "FormOfIdentification": {
                    "DocumentType": "Driving_License",
                    "DocumentNumber": "340007237",
                    "ForeignDocumentCountry": "US",
                    "DocumentIssuedState": "AL",
                    "DocumentIssuedLocalOrTribal": null,
                    "OtherLocalOrTribal": null
                }
            }
        ],
        "DeleteBeneficialOwners": [
            {
                "BeneficialOwnerId": "0a5f57f8-fa0a-45ba-a538-7f192480aaa3"
            }
        ],
        "SubmitterInformation": {
            "FirstNm": "Steve",
            "LastNm": "Austin",
            "Email": "Steve@sample.com"
        }
    }
}

Other BOIR Endpoints​

Apart from the endpoints mentioned above, you can also use the following endpoints as needed.

  • Get endpoint - This endpoint BOIR/Get can be used to retrieve information from the BOI Report created in TaxBandits.

  • List endpoint - The endpoint BOIR/List can be used to retrieve the list of BOI reports created in TaxBandits. You can retrieve the results based on reporting company, report type, SubmissionId, and various other parameters between a specified period.

  • Delete endpoint - The endpoint BOIR/Delete is used to delete the BOI reports created in TaxBandits. You must include the SubmissionId or Report Number in your request JSON to refer to the corresponding reports.

  • GetAllSubmissionId endpoint - The endpoint BOIR/GetAllSubmissionId can be used to retrieve all the SubmissionIds of the BOI Reports created in TaxBandits.

  • GetTranscript - The endpoint BOIR/GetTranscript is used to get the transcript of the BOI reports accepted/rejected by the FinCEN.

The Bottom Line​

Our BOIR API offers a comprehensive solution for simplifying compliance with beneficial ownership reporting requirements. If you have any queries, you can check out our FAQ page, or reach out to our developer support team at developer@taxbandits.com.