Corgi BankDocumentation
OpenAPI

Prepare encrypted complete FinCEN batch bytes with frozen alert sources for independent review

POST/bsa-filings

Confidential 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-KeystringRequired

Send 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 · byteOptional

Attachment 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 nullOptional

CTRRequest 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_idstringRequired

Example alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm

bankobjectRequired
20 child attributes
addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
alternate_namestringOptional
contact_extensionstringOptional
contact_officestringRequired
contact_phonestringRequired
effective_fromstring · dateRequired

A business date, YYYY-MM-DD

effective_throughstring · dateRequired

A business date, YYYY-MM-DD

einstringRequired
evidenceobjectRequired
5 child attributes
document_sha256stringRequired
known_data_completebooleanRequired
source_referencestringRequired
verified_atstring · date-timeRequired
versionstringRequired
legal_entitystringRequired
legal_namestringRequired
locationstringRequired

Exact native cash-unit location, never parsed into an address

location_addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
location_rssdstringOptional

Blank if that location has no assigned RSSD

primary_regulatorstringRequired

Actual FRB=1,FDIC=2,NCUA=3,OCC=4,IRS=7

rssdstringRequired
self_transmitterbooleanRequired
transmitter_contactstringRequired
transmitter_control_codestringRequired
transmitter_phonestringRequired
directedobject or nullOptional
5 child attributes
document_sha256stringRequired
instruction_idstringRequired
issued_onstring · dateRequired

A business date, YYYY-MM-DD

referencestringRequired
source_referencestringRequired
directed_backfilebooleanOptional
entitiesarray of objectsOptional
13 child attributes
addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
alternate_namestringOptional
business_descriptionstringRequired
customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

einstringRequired
emailstringOptional
evidenceobjectRequired
5 child attributes
document_sha256stringRequired
known_data_completebooleanRequired
source_referencestringRequired
verified_atstring · date-timeRequired
versionstringRequired
legal_namestringRequired
naicsstringOptional
phonestringOptional
phone_extensionstringOptional
tin_countrystringOptional
tin_typestringOptional

Empty or 2 = EIN, 9 = foreign

locationsarray of objectsOptional
4 child attributes
addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
kindstringRequired

Teller, atm, vault or shared_branch

locationstringRequired
rssdstringOptional
personobjectRequired
23 child attributes
addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
alternate_namestringOptional
birth_datestring · dateRequired

A business date, YYYY-MM-DD

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

drivers_licensestringRequired
emailstringOptional
evidenceobjectRequired
5 child attributes
document_sha256stringRequired
known_data_completebooleanRequired
source_referencestringRequired
verified_atstring · date-timeRequired
versionstringRequired
first_namestringRequired
genderstringRequired

Male, female, unknown; never inferred

identification_countrystringOptional
identification_issuerstringOptional

Other identification type text

identification_numberstringOptional
identification_typestringOptional

5 license, 6 passport, 7 alien registration, 999 other; empty is v1/v2 US license

last_namestringRequired
license_statestringRequired
middle_namestringOptional
occupationstringOptional
phonestringOptional
phone_extensionstringOptional
suffixstringOptional
tinstringRequired

Actual SSN/ITIN, retained only in encrypted filing documents

tin_countrystringOptional
tin_typestringOptional

Empty or 1 = SSN/ITIN, 9 = foreign

personsarray of objectsOptional
23 child attributes
addressobjectRequired
5 child attributes
citystringRequired
countrystringRequired
statestringRequired
streetstringRequired
zipstringRequired
alternate_namestringOptional
birth_datestring · dateRequired

A business date, YYYY-MM-DD

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

drivers_licensestringRequired
emailstringOptional
evidenceobjectRequired
5 child attributes
document_sha256stringRequired
known_data_completebooleanRequired
source_referencestringRequired
verified_atstring · date-timeRequired
versionstringRequired
first_namestringRequired
genderstringRequired

Male, female, unknown; never inferred

identification_countrystringOptional
identification_issuerstringOptional

Other identification type text

identification_numberstringOptional
identification_typestringOptional

5 license, 6 passport, 7 alien registration, 999 other; empty is v1/v2 US license

last_namestringRequired
license_statestringRequired
middle_namestringOptional
occupationstringOptional
phonestringOptional
phone_extensionstringOptional
suffixstringOptional
tinstringRequired

Actual SSN/ITIN, retained only in encrypted filing documents

tin_countrystringOptional
tin_typestringOptional

Empty or 1 = SSN/ITIN, 9 = foreign

prior_packet_idstringOptional
profilestringOptional
prior_packet_idstringOptional
reasonstringRequired
sarobject or nullOptional

SARRequest 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 stringsRequired
alert_sourcesarray of objectsOptional
2 child attributes
alert_idstringRequired

Example alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm

event_idsarray of stringsRequired
attachmentobject or nullOptional
2 child attributes
csvstring · byteRequired
file_namestringRequired
branchobject or nullOptional
2 child attributes
addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
rssdstringOptional
branchesarray of objectsOptional
2 child attributes
addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
rssdstringOptional
classificationsarray of objectsRequired
3 child attributes
other_textstringOptional

V2: required exactly when the subtype is the type's "Other" code

subtypestringRequired
typestringRequired
cyber_eventsarray of objectsOptional
4 child attributes
codestringRequired
datestring · dateOptional

A business date, YYYY-MM-DD

other_textstringOptional
valuestringRequired
directedobject or nullOptional

SARDirectedInstruction 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_sha256stringRequired
instruction_idstringRequired
issued_onstring · dateRequired

A business date, YYYY-MM-DD

referencestringRequired
source_referencestringRequired
dispute_idsarray of stringsOptional

DisputeIDs name retained consumer-dispute cases whose error kinds source identity-theft and payment-fraud classifications in v3.

event_idsarray of stringsRequired
filing_datestring · dateRequired

A business date, YYYY-MM-DD

institutionobjectRequired
12 child attributes
addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
contact_extensionstringOptional
contact_officestringRequired
contact_phonestringRequired
dbastringOptional
einstringRequired
internal_control_numberstringOptional
known_loss_minorintegerRequired

Investigator-reviewed known bank loss in USD cents; zero when no loss is known

legal_namestringRequired
metadata_evidence_referencestringRequired
primary_regulatorstringRequired

1 Federal Reserve, 2 FDIC, 4 OCC

rssdstringRequired
ip_addressesarray of objectsOptional
2 child attributes
addressstringRequired
datestring · dateOptional

A business date, YYYY-MM-DD

joint_filersarray of objectsOptional
6 child attributes
addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
einstringRequired
legal_namestringRequired
metadata_evidence_referencestringRequired
primary_regulatorstringRequired
rssdstringOptional
narrativeobjectRequired

Narrative 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_takenstringRequired
beneficiariesstringRequired
investigationstringRequired
languagestringRequired

En; English narrative required

losses_and_recoveriesstringRequired
related_activitystringRequired
summarystringRequired
supporting_records_referencestringRequired
why_suspiciousstringRequired
prior_activity_sequenceintegerOptional

PriorActivitySequence names the accepted predecessor activity a continuing report follows; a corrected report's single-activity predecessor needs none.

prior_packet_idstringOptional
productsarray of objectsOptional
3 child attributes
other_descriptionstringOptional
subtypestringRequired
typestringRequired
profilestringRequired
scopeobjectRequired
8 child attributes
activity_locationstringRequired

No_branch; v2 also branch

all_known_information_includedbooleanRequired
directed_backfilebooleanOptional

V1/v2 refuse; v3 requires Directed instruction evidence

institution_rolesstringRequired

Filing_activity_account_bank

joint_reportbooleanOptional

V1/v2 refuse; v3 requires JointFilers

report_kindstringRequired

Initial; v2 also continuing or corrected

subject_relationshipstringRequired

Customer_only; v2 per_subject

unsupported_factsarray of stringsOptional
subjectobjectRequired
19 child attributes
account_idstringRequired

Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm

addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
admissionstringOptional

Yes, no; blank when not applicable

alternate_namesarray of stringsOptional
birth_datestring · dateRequired

A business date, YYYY-MM-DD

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

electronic_addressesarray of objectsOptional
2 child attributes
typestringRequired
valuestringRequired
first_namestringRequired
genderstringOptional

Male, female, unknown; blank when not recorded

identificationobjectRequired
5 child attributes
issuer_countrystringRequired
issuer_statestringRequired
numberstringRequired
other_type_textstringOptional

V3: required exactly for type 999

typestringRequired

5 driver's license/state ID; v3 also 6 passport, 7 alien registration, 999 other

identity_evidence_referencestringRequired
last_namestringRequired
middle_namestringOptional
occupationstringRequired
phonesarray of objectsOptional
3 child attributes
extensionstringOptional
numberstringRequired
typestringRequired
ssnstringRequired
suffixstringOptional
tin_countrystringOptional

Required with tin_type 9

tin_typestringOptional

1 SSN (default); v3 also 9 foreign

subject_unknownobject or nullOptional
2 child attributes
account_idsarray of stringsRequired
search_evidence_referencestringRequired
subjectsarray of objectsOptional
11 child attributes
account_idsarray of stringsOptional
action_datestring · dateOptional

A business date, YYYY-MM-DD

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

entityobject or nullOptional
9 child attributes
addressobjectRequired
alternate_namesarray of stringsOptional
business_descriptionstringRequired
einstringRequired
electronic_addressesarray of objectsOptional
identity_evidence_referencestringRequired
legal_namestringRequired
naicsstringOptional
phonesarray of objectsOptional
individualobject or nullOptional
19 child attributes
account_idstringRequired

Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm

addressobjectRequired
admissionstringOptional

Yes, no; blank when not applicable

alternate_namesarray of stringsOptional
birth_datestring · dateRequired

A business date, YYYY-MM-DD

customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

electronic_addressesarray of objectsOptional
first_namestringRequired
genderstringOptional

Male, female, unknown; blank when not recorded

identificationobjectRequired
identity_evidence_referencestringRequired
last_namestringRequired
middle_namestringOptional
occupationstringRequired
phonesarray of objectsOptional
ssnstringRequired
suffixstringOptional
tin_countrystringOptional

Required with tin_type 9

tin_typestringOptional

1 SSN (default); v3 also 9 foreign

kindstringRequired

Individual or entity

no_known_accountbooleanOptional
other_relationshipstringOptional
relationship_statusstringOptional

Continues, resigned, suspended_barred, terminated

relationshipsarray of stringsRequired
rolestringOptional

Sender, receiver or both; derived from activity when accounts are known

transmitterobjectRequired
7 child attributes
addressobjectRequired
6 child attributes
citystringRequired
countrystringRequired
review_referencestringRequired

Retained actual address review, including postal consistency

statestringRequired
streetstringRequired
zipstringRequired
contact_namestringRequired
control_codestringRequired

Actual environment-specific TCC; no default

legal_namestringRequired
metadata_evidence_referencestringRequired
phonestringRequired
tinstringRequired
sourcesarray of objectsRequired
2 child attributes
activity_sequenceintegerRequired
alert_idsarray of stringsRequired
xmlstring · byteRequired

Returns

200 OK

acknowledgmentobject or nullOptional

Acknowledgment 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 objectsRequired
3 child attributes
bsa_idstringRequired
sequenceintegerRequired
warningsarray of objectsRequired
6 child attributes
codestringOptional
contextstringOptional
elementstringOptional
levelstringOptional
sequenceintegerRequired
textstringOptional
batch_sequenceintegerRequired
sha256stringRequired
submission_sequenceintegerRequired
cancellationobject or nullOptional
4 child attributes
actorstringRequired
cancelled_atstring · date-timeRequired
content_sha256stringRequired
reasonstringRequired
content_sha256stringRequired
continuesobject or nullOptional

ContinuingReference 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_sequenceintegerRequired
packet_idstringRequired
decisionobject or nullOptional
5 child attributes
actorstringRequired
content_sha256stringRequired
decided_atstring · date-timeRequired
decisionstringRequired
notestringRequired
disposalobject or nullOptional

PacketDisposal marks a packet whose encrypted documents were destroyed.

3 child attributes
disposed_atstring · date-timeRequired
documentsarray of stringsRequired
versionintegerRequired
idstringRequired
manifestobjectRequired
3 child attributes
activitiesarray of objectsRequired
5 child attributes
attachmentstringOptional

SARX only: the named single CSV support document

filing_datestringRequired
prior_bsa_idstringOptional
report_kindstringRequired
sequenceintegerRequired
formstringRequired
sha256stringRequired
nativeobject or nullOptional

NativeProvenance distinguishes an actual source-generated, locally validated form from imported XML and independently authenticated bridge reports.

6 child attributes
guide_sha256stringRequired
input_sha256stringRequired
rules_idstringRequired
source_sha256stringRequired
validation_sha256stringRequired
versionstringRequired
native_validationobject or nullOptional

NativeValidation 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_sha256stringRequired
businessobjectRequired
formstringRequired
guide_sha256stringRequired
input_sha256stringRequired
rules_idstringRequired
schemaobjectRequired
schema_bundle_sha256stringRequired
source_sha256stringRequired
validated_atstring · date-timeRequired
versionstringRequired
prepared_atstring · date-timeRequired
prepared_bystringRequired
prior_packet_idstringOptional
reasonstringRequired
released_atstring · date-time or nullOptional
responseobject or nullOptional
3 child attributes
receiptobjectRequired
2 child attributes
payloadobjectRequired

BridgePayload 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_sha256stringRequired
correlation_idstringOptional
document_sha256stringRequired
environmentstringRequired
issued_atstring · date-timeRequired
key_idstringRequired
kindstringRequired

Validation, transmission, acknowledgment, rejection

observed_atstring · date-timeRequired
packet_idstringRequired
receipt_idstringRequired

Example achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm

versionstringRequired
signaturestringRequired
recorded_atstring · date-timeRequired
verified_public_keystringRequired
source_document_sha256stringRequired
sourcesarray of objectsRequired
3 child attributes
activity_sequenceintegerRequired
alert_idstringRequired

Example alrt_2tVh8nqLxq4GbDe0K1F6S9zRcWm

sha256stringRequired
statusstringRequired
support_documentobject or nullOptional

SupportDocument 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_sequenceintegerRequired
bytesintegerRequired
file_namestringRequired
sha256stringRequired
submission_file_namestringRequired
transmissionobject or nullOptional
3 child attributes
receiptobjectRequired
2 child attributes
payloadobjectRequired

BridgePayload 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_sha256stringRequired
correlation_idstringOptional
document_sha256stringRequired
environmentstringRequired
issued_atstring · date-timeRequired
key_idstringRequired
kindstringRequired

Validation, transmission, acknowledgment, rejection

observed_atstring · date-timeRequired
packet_idstringRequired
receipt_idstringRequired

Example achr_2tVh8nqLxq4GbDe0K1F6S9zRcWm

versionstringRequired
signaturestringRequired
recorded_atstring · date-timeRequired
verified_public_keystringRequired
validationobject or nullOptional

ValidationReport 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_sha256stringRequired
business_rules_idstringRequired
business_rules_validbooleanRequired
findingsarray of stringsRequired
formstringRequired
schema_bundle_sha256stringRequired
schema_validbooleanRequired
validator_versionstringRequired
validation_profileobjectRequired
4 child attributes
business_rules_idstringRequired
environmentstringRequired

Test or production, retained with every packet

formstringRequired
schema_bundle_sha256stringRequired

Errors

Every error is a problem document with a stable code. See Errors.

400401403404409412413422424429500503

to move to open esc to close