Prepare encrypted complete FinCEN batch bytes with frozen alert sources for independent review
/bsa-filingsConfidential filing API: dedicated compliance:filings staff scope, actual verified staff identity and no API keys. Writes, approval and export require step-up within five minutes; independent approval binds exact immutable content and successful full schema/business-rule validation. XML/source and actual response bytes are encrypted and excluded from ordinary bank records/audit exports. Preparing, downloading or reporting transmission does not establish FinCEN acceptance; exact complete authenticated acknowledgment and matching transmission correlation are required. Test-environment acknowledgments remain explicitly test-only. Bounded profile: complete CTR/SAR batch XML for the configured native rules ID (CTR v1/v2/v3, SAR v1/v2); joint SARs remain unsupported. Manifest inspection is not complete XSD validation. Choose exactly one native ctr or sar request, or imported xml plus explicit sources. Native CTR profiles are own-account US teller cash (v1), aggregated US custody cash (v2) and the extended cash cut (v3: vault, non-individual titles, non-customer and agent conductors, FX, foreign identity, delivery methods, aggregate indicator and FinCEN-directed backfiling). Native SAR profiles remain the documented v1/v2 shapes. The service derives amounts, account facts and source membership, runs the pinned full XSD1.1 engine and versioned business rules, and retains separate exact-byte validation evidence. Missing facts, unsupported shapes, unavailable runtime or a changed source refuse. Native input and source metadata stay encrypted. Imported XML keeps distinct provenance and requires authenticated external full validation; manifest inspection alone is insufficient. Native approval/release rechecks the financial source, and release reruns the schema engine.
Headers
Idempotency-KeystringRequiredSend on every write that creates or changes money or state; a replay with the same key returns the original result with 200.
Body parameters
attachmentstring · byteOptionalAttachment is the exact CSV named by imported SARX XML. Native requests retain bytes on SAR.Attachment instead; this field stays empty for them.
ctrobject or nullOptionalCTRRequest contains only reviewed form metadata. Monetary amounts, account numbers, ownership, dates and complete activity membership come from native source records; there are no caller-supplied financial totals. An empty Profile is the original own-account teller profile, which uses Person and the Bank location fields. CTRProfileV2 uses Persons, Entities, Locations and, for a corrected report, PriorPacketID; those fields are absent from v1 requests so retained v1 input digests never change. CTRProfileV3 uses the v2 fields plus directed-backfile instruction evidence and extended party identity.
10 child attributes
alert_idstringRequiredExample alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm
bankobjectRequired20 child attributes
addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredalternate_namestringOptionalcontact_extensionstringOptionalcontact_officestringRequiredcontact_phonestringRequiredeffective_fromstring · dateRequiredA business date, YYYY-MM-DD
effective_throughstring · dateRequiredA business date, YYYY-MM-DD
einstringRequiredevidenceobjectRequired5 child attributes
document_sha256stringRequiredknown_data_completebooleanRequiredsource_referencestringRequiredverified_atstring · date-timeRequiredversionstringRequiredlegal_entitystringRequiredlegal_namestringRequiredlocationstringRequiredExact native cash-unit location, never parsed into an address
location_addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredlocation_rssdstringOptionalBlank if that location has no assigned RSSD
primary_regulatorstringRequiredActual FRB=1,FDIC=2,NCUA=3,OCC=4,IRS=7
rssdstringRequiredself_transmitterbooleanRequiredtransmitter_contactstringRequiredtransmitter_control_codestringRequiredtransmitter_phonestringRequireddirectedobject or nullOptional5 child attributes
document_sha256stringRequiredinstruction_idstringRequiredissued_onstring · dateRequiredA business date, YYYY-MM-DD
referencestringRequiredsource_referencestringRequireddirected_backfilebooleanOptionalentitiesarray of objectsOptional13 child attributes
addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredalternate_namestringOptionalbusiness_descriptionstringRequiredcustomer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
einstringRequiredemailstringOptionalevidenceobjectRequired5 child attributes
document_sha256stringRequiredknown_data_completebooleanRequiredsource_referencestringRequiredverified_atstring · date-timeRequiredversionstringRequiredlegal_namestringRequirednaicsstringOptionalphonestringOptionalphone_extensionstringOptionaltin_countrystringOptionaltin_typestringOptionalEmpty or 2 = EIN, 9 = foreign
locationsarray of objectsOptional4 child attributes
addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredkindstringRequiredTeller, atm, vault or shared_branch
locationstringRequiredrssdstringOptionalpersonobjectRequired23 child attributes
addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredalternate_namestringOptionalbirth_datestring · dateRequiredA business date, YYYY-MM-DD
customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
drivers_licensestringRequiredemailstringOptionalevidenceobjectRequired5 child attributes
document_sha256stringRequiredknown_data_completebooleanRequiredsource_referencestringRequiredverified_atstring · date-timeRequiredversionstringRequiredfirst_namestringRequiredgenderstringRequiredMale, female, unknown; never inferred
identification_countrystringOptionalidentification_issuerstringOptionalOther identification type text
identification_numberstringOptionalidentification_typestringOptional5 license, 6 passport, 7 alien registration, 999 other; empty is v1/v2 US license
last_namestringRequiredlicense_statestringRequiredmiddle_namestringOptionaloccupationstringOptionalphonestringOptionalphone_extensionstringOptionalsuffixstringOptionaltinstringRequiredActual SSN/ITIN, retained only in encrypted filing documents
tin_countrystringOptionaltin_typestringOptionalEmpty or 1 = SSN/ITIN, 9 = foreign
personsarray of objectsOptional23 child attributes
addressobjectRequired5 child attributes
citystringRequiredcountrystringRequiredstatestringRequiredstreetstringRequiredzipstringRequiredalternate_namestringOptionalbirth_datestring · dateRequiredA business date, YYYY-MM-DD
customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
drivers_licensestringRequiredemailstringOptionalevidenceobjectRequired5 child attributes
document_sha256stringRequiredknown_data_completebooleanRequiredsource_referencestringRequiredverified_atstring · date-timeRequiredversionstringRequiredfirst_namestringRequiredgenderstringRequiredMale, female, unknown; never inferred
identification_countrystringOptionalidentification_issuerstringOptionalOther identification type text
identification_numberstringOptionalidentification_typestringOptional5 license, 6 passport, 7 alien registration, 999 other; empty is v1/v2 US license
last_namestringRequiredlicense_statestringRequiredmiddle_namestringOptionaloccupationstringOptionalphonestringOptionalphone_extensionstringOptionalsuffixstringOptionaltinstringRequiredActual SSN/ITIN, retained only in encrypted filing documents
tin_countrystringOptionaltin_typestringOptionalEmpty or 1 = SSN/ITIN, 9 = foreign
prior_packet_idstringOptionalprofilestringOptionalprior_packet_idstringOptionalreasonstringRequiredsarobject or nullOptionalSARRequest is confidential filing input supplied by verified filing staff. Personal and institution metadata are retained assertions for independent review, not identities inferred from an alert or a successful XSD check. Initial scope supports the actual large_transaction alert's exact event link. Other alert/window semantics and additional parties require another profile. SARProfileV2 uses AlertSources, Subjects, Products and the optional Branch, Attachment, SubjectUnknown, PriorPacketID and PriorActivitySequence fields; they are absent from v1 requests so retained v1 input digests never change. SARProfileV3 uses the v2 fields plus JointFilers, Directed, Branches, CyberEvents, IPAddresses and DisputeIDs; those are absent from v1/v2 requests.
24 child attributes
alert_idsarray of stringsRequiredalert_sourcesarray of objectsOptional2 child attributes
alert_idstringRequiredExample alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm
event_idsarray of stringsRequiredattachmentobject or nullOptional2 child attributes
csvstring · byteRequiredfile_namestringRequiredbranchobject or nullOptional2 child attributes
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredrssdstringOptionalbranchesarray of objectsOptional2 child attributes
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredrssdstringOptionalclassificationsarray of objectsRequired3 child attributes
other_textstringOptionalV2: required exactly when the subtype is the type's "Other" code
subtypestringRequiredtypestringRequiredcyber_eventsarray of objectsOptional4 child attributes
codestringRequireddatestring · dateOptionalA business date, YYYY-MM-DD
other_textstringOptionalvaluestringRequireddirectedobject or nullOptionalSARDirectedInstruction is the reviewed FinCEN instruction that requires this backfile. SAR XML has no directed-backfile association flag; the generator records the instruction in FilingInstitutionNotetoFinCEN and the narrative.
5 child attributes
document_sha256stringRequiredinstruction_idstringRequiredissued_onstring · dateRequiredA business date, YYYY-MM-DD
referencestringRequiredsource_referencestringRequireddispute_idsarray of stringsOptionalDisputeIDs name retained consumer-dispute cases whose error kinds source identity-theft and payment-fraud classifications in v3.
event_idsarray of stringsRequiredfiling_datestring · dateRequiredA business date, YYYY-MM-DD
institutionobjectRequired12 child attributes
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredcontact_extensionstringOptionalcontact_officestringRequiredcontact_phonestringRequireddbastringOptionaleinstringRequiredinternal_control_numberstringOptionalknown_loss_minorintegerRequiredInvestigator-reviewed known bank loss in USD cents; zero when no loss is known
legal_namestringRequiredmetadata_evidence_referencestringRequiredprimary_regulatorstringRequired1 Federal Reserve, 2 FDIC, 4 OCC
rssdstringRequiredip_addressesarray of objectsOptional2 child attributes
addressstringRequireddatestring · dateOptionalA business date, YYYY-MM-DD
joint_filersarray of objectsOptional6 child attributes
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredeinstringRequiredlegal_namestringRequiredmetadata_evidence_referencestringRequiredprimary_regulatorstringRequiredrssdstringOptionalnarrativeobjectRequiredNarrative text is authored by the investigator. The generator adds an exact source-derived activity schedule; it never invents the reason for suspicion.
9 child attributes
actions_takenstringRequiredbeneficiariesstringRequiredinvestigationstringRequiredlanguagestringRequiredEn; English narrative required
losses_and_recoveriesstringRequiredrelated_activitystringRequiredsummarystringRequiredsupporting_records_referencestringRequiredwhy_suspiciousstringRequiredprior_activity_sequenceintegerOptionalPriorActivitySequence names the accepted predecessor activity a continuing report follows; a corrected report's single-activity predecessor needs none.
prior_packet_idstringOptionalproductsarray of objectsOptional3 child attributes
other_descriptionstringOptionalsubtypestringRequiredtypestringRequiredprofilestringRequiredscopeobjectRequired8 child attributes
activity_locationstringRequiredNo_branch; v2 also branch
all_known_information_includedbooleanRequireddirected_backfilebooleanOptionalV1/v2 refuse; v3 requires Directed instruction evidence
institution_rolesstringRequiredFiling_activity_account_bank
joint_reportbooleanOptionalV1/v2 refuse; v3 requires JointFilers
report_kindstringRequiredInitial; v2 also continuing or corrected
subject_relationshipstringRequiredCustomer_only; v2 per_subject
unsupported_factsarray of stringsOptionalsubjectobjectRequired19 child attributes
account_idstringRequiredExample acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredadmissionstringOptionalYes, no; blank when not applicable
alternate_namesarray of stringsOptionalbirth_datestring · dateRequiredA business date, YYYY-MM-DD
customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
electronic_addressesarray of objectsOptional2 child attributes
typestringRequiredvaluestringRequiredfirst_namestringRequiredgenderstringOptionalMale, female, unknown; blank when not recorded
identificationobjectRequired5 child attributes
issuer_countrystringRequiredissuer_statestringRequirednumberstringRequiredother_type_textstringOptionalV3: required exactly for type 999
typestringRequired5 driver's license/state ID; v3 also 6 passport, 7 alien registration, 999 other
identity_evidence_referencestringRequiredlast_namestringRequiredmiddle_namestringOptionaloccupationstringRequiredphonesarray of objectsOptional3 child attributes
extensionstringOptionalnumberstringRequiredtypestringRequiredssnstringRequiredsuffixstringOptionaltin_countrystringOptionalRequired with tin_type 9
tin_typestringOptional1 SSN (default); v3 also 9 foreign
subject_unknownobject or nullOptional2 child attributes
account_idsarray of stringsRequiredsearch_evidence_referencestringRequiredsubjectsarray of objectsOptional11 child attributes
account_idsarray of stringsOptionalaction_datestring · dateOptionalA business date, YYYY-MM-DD
customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
entityobject or nullOptional9 child attributes
addressobjectRequiredalternate_namesarray of stringsOptionalbusiness_descriptionstringRequiredeinstringRequiredelectronic_addressesarray of objectsOptionalidentity_evidence_referencestringRequiredlegal_namestringRequirednaicsstringOptionalphonesarray of objectsOptionalindividualobject or nullOptional19 child attributes
account_idstringRequiredExample acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm
addressobjectRequiredadmissionstringOptionalYes, no; blank when not applicable
alternate_namesarray of stringsOptionalbirth_datestring · dateRequiredA business date, YYYY-MM-DD
customer_idstringRequiredExample cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm
electronic_addressesarray of objectsOptionalfirst_namestringRequiredgenderstringOptionalMale, female, unknown; blank when not recorded
identificationobjectRequiredidentity_evidence_referencestringRequiredlast_namestringRequiredmiddle_namestringOptionaloccupationstringRequiredphonesarray of objectsOptionalssnstringRequiredsuffixstringOptionaltin_countrystringOptionalRequired with tin_type 9
tin_typestringOptional1 SSN (default); v3 also 9 foreign
kindstringRequiredIndividual or entity
no_known_accountbooleanOptionalother_relationshipstringOptionalrelationship_statusstringOptionalContinues, resigned, suspended_barred, terminated
relationshipsarray of stringsRequiredrolestringOptionalSender, receiver or both; derived from activity when accounts are known
transmitterobjectRequired7 child attributes
addressobjectRequired6 child attributes
citystringRequiredcountrystringRequiredreview_referencestringRequiredRetained actual address review, including postal consistency
statestringRequiredstreetstringRequiredzipstringRequiredcontact_namestringRequiredcontrol_codestringRequiredActual environment-specific TCC; no default
legal_namestringRequiredmetadata_evidence_referencestringRequiredphonestringRequiredtinstringRequiredsourcesarray of objectsRequired2 child attributes
activity_sequenceintegerRequiredalert_idsarray of stringsRequiredxmlstring · byteRequiredReturns
200 OK
acknowledgmentobject or nullOptionalAcknowledgment is one complete FinCEN XML 2.0 batch response. Parsing establishes its structure and exact activity membership, not the response's authenticity or that it belongs to a particular submitted file. The filing service must bind the original response bytes to an authenticated transmission receipt before use.
4 child attributes
activitiesarray of objectsRequired3 child attributes
bsa_idstringRequiredsequenceintegerRequiredwarningsarray of objectsRequired6 child attributes
codestringOptionalcontextstringOptionalelementstringOptionallevelstringOptionalsequenceintegerRequiredtextstringOptionalbatch_sequenceintegerRequiredsha256stringRequiredsubmission_sequenceintegerRequiredcancellationobject or nullOptional4 child attributes
actorstringRequiredcancelled_atstring · date-timeRequiredcontent_sha256stringRequiredreasonstringRequiredcontent_sha256stringRequiredcontinuesobject or nullOptionalContinuingReference names the exact accepted SAR activity a continuing report follows. It is plaintext packet content so admission guards can bind it.
2 child attributes
activity_sequenceintegerRequiredpacket_idstringRequireddecisionobject or nullOptional5 child attributes
actorstringRequiredcontent_sha256stringRequireddecided_atstring · date-timeRequireddecisionstringRequirednotestringRequireddisposalobject or nullOptionalPacketDisposal marks a packet whose encrypted documents were destroyed.
3 child attributes
disposed_atstring · date-timeRequireddocumentsarray of stringsRequiredversionintegerRequiredidstringRequiredmanifestobjectRequired3 child attributes
activitiesarray of objectsRequired5 child attributes
attachmentstringOptionalSARX only: the named single CSV support document
filing_datestringRequiredprior_bsa_idstringOptionalreport_kindstringRequiredsequenceintegerRequiredformstringRequiredsha256stringRequirednativeobject or nullOptionalNativeProvenance distinguishes an actual source-generated, locally validated form from imported XML and independently authenticated bridge reports.
6 child attributes
guide_sha256stringRequiredinput_sha256stringRequiredrules_idstringRequiredsource_sha256stringRequiredvalidation_sha256stringRequiredversionstringRequirednative_validationobject or nullOptionalNativeValidation retains the complete deterministic engine reports without pretending the bank's local validator signed as an independent bridge. Maps marshal canonically across PostgreSQL JSONB key-order normalization.
11 child attributes
batch_sha256stringRequiredbusinessobjectRequiredformstringRequiredguide_sha256stringRequiredinput_sha256stringRequiredrules_idstringRequiredschemaobjectRequiredschema_bundle_sha256stringRequiredsource_sha256stringRequiredvalidated_atstring · date-timeRequiredversionstringRequiredprepared_atstring · date-timeRequiredprepared_bystringRequiredprior_packet_idstringOptionalreasonstringRequiredreleased_atstring · date-time or nullOptionalresponseobject or nullOptional3 child attributes
receiptobjectRequired2 child attributes
payloadobjectRequiredBridgePayload attests actual validator or transmission-system evidence. It is not a FinCEN protocol. The bridge must supply the real retained document bytes; a SHA entered by bank staff alone never establishes validation or acceptance.
11 child attributes
batch_sha256stringRequiredcorrelation_idstringOptionaldocument_sha256stringRequiredenvironmentstringRequiredissued_atstring · date-timeRequiredkey_idstringRequiredkindstringRequiredValidation, transmission, acknowledgment, rejection
observed_atstring · date-timeRequiredpacket_idstringRequiredreceipt_idstringRequiredExample achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm
versionstringRequiredsignaturestringRequiredrecorded_atstring · date-timeRequiredverified_public_keystringRequiredsource_document_sha256stringRequiredsourcesarray of objectsRequired3 child attributes
activity_sequenceintegerRequiredalert_idstringRequiredExample alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm
sha256stringRequiredstatusstringRequiredsupport_documentobject or nullOptionalSupportDocument is the one CSV attachment a SARX activity names, whether the batch was generated natively or imported with those exact bytes. The SAR XML User Guide 1.6 (section 4.5 and Attachment E) permits one MS Excel-compatible CSV of at most one megabyte per SAR, recorded by its full name in OriginalAttachmentFileName; batch filers place each CSV in the attachment zip file named <activity SeqNum>_<OriginalAttachmentFileName>. The exact bytes are a separate encrypted payload released only with the approved batch naming them.
5 child attributes
activity_sequenceintegerRequiredbytesintegerRequiredfile_namestringRequiredsha256stringRequiredsubmission_file_namestringRequiredtransmissionobject or nullOptional3 child attributes
receiptobjectRequired2 child attributes
payloadobjectRequiredBridgePayload attests actual validator or transmission-system evidence. It is not a FinCEN protocol. The bridge must supply the real retained document bytes; a SHA entered by bank staff alone never establishes validation or acceptance.
11 child attributes
batch_sha256stringRequiredcorrelation_idstringOptionaldocument_sha256stringRequiredenvironmentstringRequiredissued_atstring · date-timeRequiredkey_idstringRequiredkindstringRequiredValidation, transmission, acknowledgment, rejection
observed_atstring · date-timeRequiredpacket_idstringRequiredreceipt_idstringRequiredExample achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm
versionstringRequiredsignaturestringRequiredrecorded_atstring · date-timeRequiredverified_public_keystringRequiredvalidationobject or nullOptionalValidationReport is the bridge's complete schema + filing-rule result for an immutable configured ruleset. Findings are retained even on failure. The actual validator implementation must run the full schemas and business rules; manifest inspection is not sufficient to issue a successful report.
8 child attributes
batch_sha256stringRequiredbusiness_rules_idstringRequiredbusiness_rules_validbooleanRequiredfindingsarray of stringsRequiredformstringRequiredschema_bundle_sha256stringRequiredschema_validbooleanRequiredvalidator_versionstringRequiredvalidation_profileobjectRequired4 child attributes
business_rules_idstringRequiredenvironmentstringRequiredTest or production, retained with every packet
formstringRequiredschema_bundle_sha256stringRequiredErrors
Every error is a problem document with a stable code. See Errors.
400401403404409412413422424429500503