Beneficial Ownership Information Report

System-to-System API User Guide

Financial Crimes Enforcement Network

U.S. Department of the Treasury
Version 1.0.1 February 2024
Revision History
Version Number Date Change Description
1.0 1/1/2024 Initial version
1.0.1 2/13/2024 II. BOIR API Access: Updated “User Test” API references to
“Sandbox” API (Note: This update does not impact the API
URLs; however, the “scope” used in the HTTP request to
obtain the Sandbox access token is changed from “BOSS-
EFILE-USER-TEST” to “BOSS-EFILE-SANDBOX”. Also removed
the statement that the same ClientID/secret can be used
for both sandbox and production APIs; rather, approved API
users are issued unique credentials for each environment.

Disclaimer: These instructions are explanatory only and do not supplement or modify any
obligations imposed by statute or regulation. FinCEN may also revise these instructions to clarify
or update content. For additional and latest information, consult www.fincen.gov/boi.

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

i
Table of Contents
Revision History ................................................................................................................................ i
1. BOIR System-to-System Filing Introduction ................................................................................ 1
2. BOIR API Access .......................................................................................................................... 2
3. BOIR Submission & Tracking Process.......................................................................................... 4
3.1.1. Initiate BOIR Submission via /processId ......................................................................... 5
3.1.2. Upload Identifying Document Image(s) via /attachments.............................................. 6
3.1.3. Upload BOIR XML via /upload......................................................................................... 7
3.1.4. Track Submission Status via /submissionStatus ............................................................. 8
3.1.5. Retrieve the BOIR Transcript via /transcript.................................................................... 9
3.1 Common Response Codes ...................................................................................................... 9
3.1.1. Response Examples ........................................................................................................ 10
3.1.1.1. “/processId: BOIR XML submission initiation” ........................................................... 10
3.1.1.2. “/attachment: Attachment upload success”............................................................... 10
3.1.1.3. “/attachment: Invalid attachment file type”............................................................... 11
3.1.1.4. “/upload: BOIR XML file upload”................................................................................. 11
3.1.1.5. “/upload: Invalid/Incomplete submitter information” ............................................... 12
3.1.1.6. “/submissionStatus: submission_validation_passed”................................................ 12
3.1.1.7. “/submissionStatus: submission_rejected” ............................................................... 13
3.1.1.8 “/submissionStatus: validation_failed (attachments not uploaded)” ......................... 14
3.1.1.9. “/submissionStatus: submission_accepted” .............................................................. 15
3.1.1.10. “/submissionStatus: incorrect processID”................................................................ 16
3.1.1.11. “/transcript: submission_rejected (Initial filing exists for this entity)”...................... 17
4. Error Codes List ......................................................................................................................... 18

Table 1 - BOI E-Filing API URLs: User Test & Production ................................................................... 2
Table 2 - HTTP request to obtain access token ................................................................................ 3
Table 3 - GET /processId .................................................................................................................. 5
Table 4 - POST /attachments ........................................................................................................... 6
Table 5 - POST /upload .................................................................................................................... 7
Table 6 - GET /submissionStatus ...................................................................................................... 8
Table 7 - GET /transcript .................................................................................................................. 9
Table 8 - Common Response Codes ................................................................................................ 9
Table 9 - Rejection Error Codes ...................................................................................................... 18

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

ii
I. BOIR System-to-System Filing Introduction
The Beneficial Ownership Information Report (BOIR) collects information about the beneficial
owner(s) and company applicant(s) associated with a reporting company. FinCEN supports two
primary methods of filing when it comes to the BOIR: (1) “Form” based data collection via PDF
BOIR or Online BOIR (which require very minimal setup to use), and (2) “System-to-System” based
data collection via a REST API. This guide focuses on the System-to-System API filing method,
specifically how to access the BOI E-Filing API and submit your BOIR information to FinCEN,
interpret the submission response JSON, and understand what data validations and potential
system processing errors may occur during the filing process.

IMPORTANT: This guide does NOT include instructions regarding how to format your BOIR
data prior to filing, which must follow FinCEN’s XML standard format. Please refer to the
associated “Beneficial Ownership Information Report System-to-System XML User Guide”
for more details.

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

1
II. BOIR API Access
To obtain access to the BOI E-Filing API, contact FinCEN via the following contact us form to
request access: https://www.fincen.gov/contact. Please be sure to include the following in
your inquiry:

1. Select the topic associated with the Beneficial Ownership (BO) / Corporate
Transparency Act (CTA)

2. Select the subject associated with API requests.

3. Indicate in the message body that you are requesting API access credentials to
connect to the BOI E-Filing API.

This will prompt FinCEN to reach out to you directly to coordinate the creation of your access
credentials (i.e., clientId and secret) to use with the BOI E-Filing API. FinCEN also provides
access credentials to use with its BOI E-Filing *SANDBOX* API, which allows you to test the
submission process before submitting live data in production. Credentials will be provided
if access is approved by FinCEN. Note the following hostnames associated with the BOI E-
Filing *Sandbox* and * Production* APIs:
Table 1 - BOI E-Filing API URLs: Sandbox & Production
Environment URL to use in API request
BOI E-Filing *Sandbox* API https://boiefiling-api.user-test.fincen.gov/preprod
BOI E-Filing *Production* API https://boiefiling-api.fincen.gov/prod

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

2
After access credentials are obtained and you are ready to submit a BOIR, the user’s system will
need to retrieve an access token to access the API. The token will be valid for one hour after
retrieval and can be used for multiple API requests across multiple different submissions. The
HTTP request to obtain the token is as such:
Table 2 - HTTP request to obtain access token
Comments
Endpoint POST https://iam.fincen.gov/am/oauth2/
realms/root/realms/Finance/access_
token
Request Authorization “Basic <credentials>” <credentials> is the
Headers base64-encoded value
of “clientId:secret”
(without the quotes)
Request grant_type: client_credentials <scope> is “BOSS-
Body scope: <scope> EFILE-SANDBOX” for
Test or “BOSS- EFILE”
for Production
(without the quotes)
Content-Type application/x-www-form-urlencoded
Response Body { <access_token>
“access_token”: “<access_token>”, will be used in the
Authorization header
“scope”: “BOSS-EFILE”,
for all BOI E-Filing API
“token_type”: “Bearer”, requests
“expires_in”: 3599
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

3
III. BOIR Submission & Tracking Process
As noted above, before you can begin the filing process, you must obtain an access token from
FinCEN’s system by presenting your valid clientId and secret (see above section “BOIR API
Access” for details) via a REST API call. Once the access token is retrieved, it must be included in
the request header throughout the BOIR filing process which can be used for multiple BOIR filings
as long as it is no later than one hour after retrieval.
The following is an overview of the BOIR filing processing via API:
1. Initiate BOIR Submission via /processId: To initiate the BOIR filing process, the
user’s system sends a GET request to the /processId resource, resulting in a process ID
returned (e.g., “BOIR230921650c447660”).
2. Upload Identifying Document Image(s) via /attachments: User’s system uploads
the identifying document image for each Company Applicant and Beneficial Owner
reported in the BOIR via the /attachments resource, resulting in an upload status
returned (e.g., “upload_success”). If no Company Applicant and/or Beneficial Owner
are being reported in the BOIR, then skip this step.
NOTE: The filenames for each image attachment in the BOIR must be
unique and referenced in the associated BOIR XML under the element
“OriginalAttachmentFileName” for each Company Applicant and Beneficial Owner
being reported.
3. Upload BOIR XML via /upload: User’s system uploads a single BOIR as an XML file
binary via the /upload resource, returning a submission status for the process ID (e.g.,
“submission_initiated”)
4. Track Submission Status via /submissionStatus: User’s system begins querying
the status of the submission via the /submissionStatus resource (e.g., “submission_
accepted”).
Retrieve the BOIR Transcript via /transcript: If a status of “submission_accepted”
or “submission_rejected” is returned, filer’s system retrieves the transcript PDF of
the BOIR as binary data via the /transcript resource. The /transcript resource also
produces the status of the submission.
NOTE: The binary data for the transcript is base64-encoded. As an example, in
JavaScript, to create the PDF file, the binary data will need to be decoded from
base64 and then downloaded as a blob with the mime-type “application/pdf”.
The final status of your BOIR filing is either “submission_accepted”, “submission_rejected”, or
“submission_failed”. If you receive a status with “failed” or “rejected” in the value, this means that
FinCEN could NOT process your BOIR submission and you should take steps to resolve the reason
for the failure/rejection (refer to the list of common response codes and errors later in this guide
for additional information).

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

4
3.1.1 Initiate BOIR Submission via /processId
Table 3 - GET /processId
Comments
Endpoint GET /processId Retrieves a processId
Path Parameters N/A
Request Headers Authorization "Bearer <access_
token>"
Request Body N/A
Response Content-Type application/json
Body JSON payload for
successful request:
{ processId:
<processId> }

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

5
3.1.2 Upload Identifying Document Image(s) via /attachments
Table 4 - POST /attachments
Comments
Endpoint POST /attachments/{processId}/ Upload a single image
{fileName} file
Note: uploading
another image file
with same fileName
will replace the
previous one
Path Parameters processId processId from /processId
fileName Image filename, with File name for the
extension (must match image must end in
a value recorded for the .jpg, .jpeg, .png, or
OriginalAttachmentFileName .pdf and must be URI
element in the BOIR XML) encoded.
Filename limitations:
Letters, numbers, _ !
@#$%()=+[]{}|;
~-
Request Headers Content-Type application/binary
Authorization "Bearer <access_token>"

Request Body Image file’s binary data Image file should be

no greater than 4MB in
file size
Response Content-Type application/json
Body JSON payload: Upload status values:
{ status: <upload status>, • upload_success
message: <Additional • upload_failed
details>}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

6
3.1.3 Upload BOIR XML via /upload
Table 5 - POST /upload
Comments
Endpoint POST /upload/BOIR/ Upload and submit
{processId}/ the BOIR XML
{xmlFileName}
Path Parameters processId processId from /
processId
xmlFileName XML file name File name for the
XML file must end in
.xml and must be URI
encoded.
Filename limitations:
Letters, numbers, _ !
@#$%()=+[]{}|;
~-
Request Headers Content-Type application/xml
Authorization "Bearer <access_
token>"
Request Body XML file binary data
Response Content-Type application/json
Body JSON payload for
successful upload:
{ processId:
<processId>, status:
“submission_
initiated” }

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

7
3.1.4 Track Submission Status via /submissionStatus

Table 6 - GET /submissionStatus

Comments
Endpoint GET /submissionStatus/ Check the status of a
{processId} submitted BOIR
Path Parameters processId processId from /processId
Request Headers Authorization “Bearer <access_token>”
Request Body N/A
Response Content-Type application/json

Body JSON payload - submission Status values:

status • submission_initiated
• submission_
processing
• submission_
validation_passed
• submission_
validation_failed
• submission_
accepted
• submission_rejected
• submission_failed

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

8
3.1.5 Retrieve the BOIR Transcript via /transcript
Table 7 - GET /transcript
Comments
Endpoint GET /transcript/{processId} Retrieve the transcript
(and status) of a
submitted BOIR
Path Parameters processId processId from /
processId
Request Headers Authorization "Bearer <access_
token>"
Request Body N/A
Response Content-Type application/json
Body submission status:
{status: <status>}
OR
submission status +
PDF file binary:
{status: <status>,
pdfBinary: <PDF
binary>}

3.1. Common Response Codes

Table 8 - Common Response Codes
Response Code Description Comments
200 Successful API call (none)
400 Validation Failure Initial validation failed
401 Authentication Unauthorized
403 Authorization Forbidden
404 Not Found Unable to retrieve status/transcript
413 Payload Too Large Image attachment file exceeds 5MB
415 Unsupported Media Type Image attachment file type is not supported
429 Throttling Too many requests
502/504 Dependency Issues Bad Gateway/Gateway Timeout
500/503 Unhandled Errors Internal Server Error, Service unavailable

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

9
3.1. Response Examples
3.1.0.1. “/processId: BOIR XML submission initiation”
/processId

{
statusCode: 200,
body: {
“processId”: “BOIR230928X6515f3081”
}
}
3.1.0.2. “/attachment: Attachment upload success”
/attachment/BOIR230928X6515f3081/bill_spencer.jpg

{
statusCode: 200,
body: {
“code”: “upload_success”,
“message”: “bill_spencer.jpg has been successfully uploaded.”
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

10
 3.1.0.3. “/attachment: Invalid attachment file type”
/attachment/BOIR230928X6515f3081/bill_spencer.gif

{
statusCode: 400,
body: {
“error”: {
“code”: “file_name_invalid”,
“message”: “Invalid file name: bill_spencer.gif”,
“details”: “The file name provided is invalid. Allowed characters:
alphanumeric ! @ # $ % ( ) _ - = + [ ] { } | ; ~ and space.”,
“help”: “Refer to the provided API documentation from FinCEN for
guidance.”
}
}
}
3.1.0.4. “/upload: BOIR XML file upload”
/upload/BOIR/BOIR230928X6515f3081/BOIR.xml

{
statusCode: 200,
body: {
“processId”: “BOIR230928X6515f3081”,
“submissionStatus”: “submission_initiated”
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

11
 3.1.0.5. “/upload: Invalid/Incomplete submitter information”
/upload/BOIR/<processId>/BOIR.xml

{
statusCode: 200,
body: {
“error”: {
“code”: “submitter_info_invalid”,
“message”: “Invalid Submitter information: Email, first name, last name,
and processId are required”,
“details”: “Please validate the submitter information in the XML.”,
“help”: “Refer to the provided API documentation from FinCEN for
guidance.”
}
}
}
3.1.0.6. “/submissionStatus: submission_validation_passed”
/submissionStatus/BOIR230928X6515f3081

{
statusCode: 200,
body: {
“processId”: “BOIR230928X6515f3081”,
“submissionStatus”: “submission_validation_passed”,
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

12
 3.1.0.7. “/submissionStatus: submission_rejected”
/submissionStatus/BOIR230928X6515f3081

{
statusCode: 200,
body: {
“processId”: “BOIR230928X6515f3081”,
“submissionStatus”: “submission_rejected”,
“BOIRID”: “”,
“fincenID”: “”,
“errors”: [
{
“ErrorElementName”: “FinCENID”,
“ErrorContextText”: “Party[PartySeqNum=4, DocumentSeqNum=2,
BORXmlSubmissionSeqNum=1]”,
“ErrorLevelText”: “FATAL”,
“ErrorText”: “Initial BOIR already has been filed for the reporting
company recorded in the initial BOIR filing. Please try again. If this problem persists, please
contact the FinCEN Contact Center for assistance.”,
“ErrorCode”: “SBE02”,
“ErrorTypeCode”: “SBE02”
}
],
“initiatedTimestamp”: “2023-09-28T21:56:58Z”,
“firstName”: “Test”,
“lastName”: “Tester”,
“email”: “test@test.net”
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

13
 3.1.0.8. “/submissionStatus: validation_failed (attachments not uploaded)”
/submissionStatus/BOIR2309286515f80dD0

{
statusCode: 200,
body: {
{
“processId”: “ BOIR2309286515f80dD0”,
“submissionStatus”: “submission_validation_failed”,
“validationErrors”: [
{
“errorMessage”: “Unable to find joe_hamilton.jpg in uploaded attachments.”
},
{
“errorMessage”: “Unable to find bill_spencer.jpg in uploaded attachments.”
}
]
}
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

14
 3.1.0.9. “/submissionStatus: submission_accepted”

/submissionStatus/BOIR2309286515fa4eY0

{
“processId”: “BOIR2309286515fa4eY0”,
“submissionStatus”: “submission_accepted”,
“BOIRID”: “50000000003688”,
“fincenID”: “200000000843”,
“errors”: [
{
“ErrorElementName”: “”,
“ErrorContextText”: “”,
“ErrorLevelText”: “”,
“ErrorText”: “”,
“ErrorCode”: “”,
“ErrorTypeCode”: “”
}
],
“initiatedTimestamp”: “2023-09-28T22:12:48Z”,
“firstName”: “Test”,
“lastName”: “Tester”,
“email”: “test@test.net”

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

15
 3.1.0.10. “/submissionStatus: incorrect processID”/submissionStatus/
BOIR2309286515fa4eY0

{
“processId”: “BOIR2309286515fa4eY0”,
“submissionStatus”: “submission_accepted”,
“BOIRID”: “50000000003688”,
“fincenID”: “200000000843”,
“errors”: [
{
“ErrorElementName”: “”,
“ErrorContextText”: “”,
“ErrorLevelText”: “”,
“ErrorText”: “”,
“ErrorCode”: “”,
“ErrorTypeCode”: “”
}
],
“initiatedTimestamp”: “2023-09-28T22:12:48Z”,
“firstName”: “Test”,
“lastName”: “Tester”,
“email”: “test@test.net”
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

16
 3.1.0.11. “/transcript: submission_rejected (Initial filing exists for this entity)”
/transcript/BOIR230928X6515f3081

{
statusCode: 200,
body: {
“status”: {
“processId”: “BOIR230928X6515f3081”,
“submissionStatus”: “submission_rejected”,
“BOIRID”: “”,
“fincenID”: “”,
“errors”: [
{
“ErrorElementName”: “FinCENID”,
“ErrorContextText”: “Party[PartySeqNum=4,
DocumentSeqNum=2, BORXmlSubmissionSeqNum=1]”,
“ErrorLevelText”: “FATAL”,
“ErrorText”: “Initial BOIR already has been filed for the
reporting company recorded in the initial BOIR filing. Please try again. If this problem persists,
please contact the FinCEN Contact Center for assistance.”,
“ErrorCode”: “SBE02”,
“ErrorTypeCode”: “SBE02”
}
],
“initiatedTimestamp”: “2023-09-28T21:56:58Z”,
“firstName”: “Test”,
“lastName”: “Tester”,
“email”: “test@test.net”
},
“pdfBinary”:
“JVBERi0xLjcKJf////8KOCAwIG9iago8PAovVHlwZSAvRXh0R1N0YXRlCi9jYSAxCj4...”
}
}

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

17
IV. Error Codes List
The following list of errors will result in a final status of submission_rejected. This means that
your BOIR submission could not be assigned a BOIR ID by FinCEN and you must take action to fix
the error and resubmit. As stated in the error descriptions below, if the problem (error) persists,
please contact FinCEN’s contact center for further assistance:
Table 9 - Rejection Error Codes
Error code Error description Type of filing Associated How you should
party respond…
SBE01 BOIR could not be N/A N/A Resubmit the BOIR as-is.
processed by FinCEN
at this time. Please try
again. If this problem
persists, please contact
the FinCEN Contact
Center for assistance.
SBE02 Initial BOIR already Initial report Reporting Resubmit the BOIR after
has been filed for the Company the following:
reporting company • If you are attempting to
recorded in the initial file an initial report, ensure
BOIR filing. Please try the name and TIN for the
again. If this problem Reporting Company (Part
persists, please contact I) is correct.
the FinCEN Contact
• If you are not attempting
Center for assistance.
to file an initial report,
ensure the correct filing
type is indicated.
SBE03 FinCEN ID entered for Initial report Company Resubmit the BOIR after
a Company Applicant Applicant the following:
or Beneficial Owner Beneficial • Ensure that the FinCEN
cannot be matched Owner ID(s) recorded in the BOIR
to an existing FinCEN are correct.
ID. Please try again. If
this problem persists,
please contact the
FinCEN Contact Center
for assistance.

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

18
SBE04 Reporting Company Update prior Reporting Resubmit the BOIR after
information entered in report Company the following:
Type of filing Items 1(e)- Correct prior • Ensure the name and TIN
(h) cannot be matched report recorded for Item 1 (Type
to an existing Reporting of filing) for the Reporting
Newly
Company. Please try Company matches the
exempt
again. If this problem Reporting Company name
entity
persists, please contact and TIN for the most
the FinCEN Contact recent BOIR filing.
Center for assistance.
SBE05 Reporting Company Update prior Reporting Resubmit the BOIR after
information recorded in report Company the following:
Type of filing Items 1(e)- Correct prior • Ensure the name and TIN
(h) cannot be matched report recorded for Item 1 (Type
to a prior BOIR filing. of filing) for the Reporting
Newly
Please try again. If Company matches the
exempt
this problem persists, Reporting Company name
entity
please contact the and TIN for the most
FinCEN Contact Center recent BOIR filing.
for assistance.
SBE06 FinCEN ID entered for Update prior Company Resubmit the BOIR after
a Company Applicant report Applicant the following:
or Beneficial Owner Correct prior Beneficial • Ensure that the FinCEN
cannot be matched report Owner ID(s) recorded in the BOIR
to an existing FinCEN are correct.
Newly
ID. Please try again. If
exempt
this problem persists,
entity
please contact the
FinCEN Contact Center
for assistance.

Beneficial Ownership Information Reports: System-to-System API User Guide

February 2024 - Version 1.0.1

19