Reports

Overview

The Reports module automates the creation of regulatory filings required under the CBN AML/CFT Act. When transactions trigger certain rules, the system can auto-generate Suspicious Activity Reports (SAR), Currency Transaction Reports (CTR), and Foreign Transaction Reports (FTR). Compliance officers can also generate these manually.

Common Workflows

Auto-generation: A customer makes a cash deposit ≥ ₦5M → The system auto-creates a CTR → The compliance officer reviews and approves it → The XML is submitted to CBN. Manual SAR filing: An officer investigates a structuring case → Manually generates a SAR from the case → Attaches supporting documents → Approves for regulatory submission.

Permissions

Action	Who Can Do It
Generate reports	`BANK_ADMIN`, `COMPLIANCE_OFFICER`
List, view reports	All authenticated users
Approve, file reports	`BANK_ADMIN`, `COMPLIANCE_OFFICER`

Report Types

Type	Trigger	Filing Threshold
SAR	Suspicious activity (structuring, sanctions, fraud)	Any suspicious pattern
CTR	Large cash transaction	Cash ≥ ₦5,000,000
FTR	International transfer	Receiver country ≠ `NG`

Report Statuses

Status	Meaning
`DRAFT`	Auto-generated, awaiting review
`PENDING_REVIEW`	Submitted for officer approval
`APPROVED`	Approved for CBN submission
`FILED`	Submitted to CBN
`REJECTED`	Rejected, needs revision

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/reports/sar`	Generate a Suspicious Activity Report
`POST`	`/api/v1/reports/ctr`	Generate a Currency Transaction Report
`POST`	`/api/v1/reports/ftr`	Generate a Foreign Transaction Report
`GET`	`/api/v1/reports`	List generated reports
`GET`	`/api/v1/reports/:id`	Retrieve report details
`GET`	`/api/v1/reports/:id/xml`	Download report as CBN XML
`PATCH`	`/api/v1/reports/:id/approve`	Approve report for submission
`PATCH`	`/api/v1/reports/:id/file`	Mark report as filed with CBN

Generate SAR

Create a Suspicious Activity Report for investigated cases. Request Body

Field	Type	Required	Description
`caseId`	`string`	✅	Related case UUID
`title`	`string`	✅	Report title
`description`	`string`	✅	Narrative of suspicious activity
`suspicionType`	`string`		`STRUCTURING`, `SANCTIONS`, `FRAUD`, `OTHER`

Example Request

curl -X POST /v1/reports/sar \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "caseId": "case_12345abcde",
    "title": "Structuring Pattern — 4 Deposits in 3 Hours",
    "description": "Customer made 4 deposits totaling ₦4.8M in 3 hours, just below the CTR threshold.",
    "suspicionType": "STRUCTURING"
  }'

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "rep_001",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "reportType": "SAR",
    "reportNumber": "SAR-2026-00001",
    "title": "Structuring Pattern — 4 Deposits in 3 Hours",
    "status": "DRAFT",
    "xmlContent": null,
    "jsonData": null,
    "relatedCaseId": "case_12345abcde",
    "generatedBy": "550e8400-e29b-41d4-a716-446655440000",
    "approvedBy": null,
    "filedAt": null,
    "createdAt": "2026-05-16T11:00:00Z",
    "updatedAt": "2026-05-16T11:00:00Z"
  }
}

Generate CTR

Create a Currency Transaction Report for large cash transactions. Request Body

Field	Type	Required	Description
`transactionId`	`string`	✅	Triggering transaction UUID
`title`	`string`	✅	Report title
`amount`	`number`	✅	Transaction amount
`currency`	`string`		Defaults to `NGN`
`customerId`	`string`	✅	Customer UUID
`branchCode`	`string`		Branch where transaction occurred

Example Request

curl -X POST /v1/reports/ctr \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "tx_cash_999",
    "title": "Cash Deposit ₦5M — CTR Filing",
    "amount": 5000000,
    "currency": "NGN",
    "customerId": "cust_001",
    "branchCode": "LAG-01"
  }'

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "rep_002",
    "reportType": "CTR",
    "reportNumber": "CTR-2026-00001",
    "title": "Cash Deposit ₦5M — CTR Filing",
    "status": "DRAFT",
    "relatedCaseId": null,
    "generatedBy": "550e8400-e29b-41d4-a716-446655440000",
    "approvedBy": null,
    "filedAt": null,
    "createdAt": "2026-05-16T11:30:00Z",
    "updatedAt": "2026-05-16T11:30:00Z"
  }
}

Generate FTR

Create a Foreign Transaction Report for cross-border transfers. Request Body

Field	Type	Required	Description
`transactionId`	`string`	✅	Triggering transaction UUID
`title`	`string`	✅	Report title
`foreignAmount`	`number`	✅	Amount in foreign currency
`foreignCurrency`	`string`	✅	Foreign currency code
`destinationCountry`	`string`	✅	ISO 3166-1 alpha-2 code
`purposeOfTransfer`	`string`		Reason for transfer

Example Request

curl -X POST /v1/reports/ftr \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "tx_intl_444",
    "title": "International Transfer — School Fees",
    "foreignAmount": 10000,
    "foreignCurrency": "USD",
    "destinationCountry": "US",
    "purposeOfTransfer": "School fees payment"
  }'

Example Response — 201 Created

{
  "success": true,
  "data": {
    "id": "rep_003",
    "reportType": "FTR",
    "reportNumber": "FTR-2026-00001",
    "title": "International Transfer — School Fees",
    "status": "DRAFT",
    "relatedCaseId": null,
    "generatedBy": "550e8400-e29b-41d4-a716-446655440000",
    "approvedBy": null,
    "filedAt": null,
    "createdAt": "2026-05-16T12:00:00Z",
    "updatedAt": "2026-05-16T12:00:00Z"
  }
}

List Reports

Retrieve generated reports with filtering. The list view excludes xmlContent and jsonData for performance. Query Parameters

Parameter	Type	Default	Description
`type`	`string`	—	`SAR`, `CTR`, `FTR`
`status`	`string`	—	`DRAFT`, `PENDING_REVIEW`, `APPROVED`, `FILED`, `REJECTED`
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page

Example Request

curl -X GET "/v1/reports?type=SAR&status=DRAFT&page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"

Example Response — 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "rep_001",
        "reportType": "SAR",
        "reportNumber": "SAR-2026-00001",
        "title": "Structuring Pattern — 4 Deposits in 3 Hours",
        "status": "DRAFT",
        "generatedBy": "550e8400-e29b-41d4-a716-446655440000",
        "approvedBy": null,
        "filedAt": null,
        "createdAt": "2026-05-16T11:00:00Z",
        "updatedAt": "2026-05-16T11:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Get Report Detail

Retrieve the full report including XML content and structured JSON data. Path Parameters

Parameter	Type	Description
`id`	`string`	Report UUID

Example Request

curl -X GET /v1/reports/rep_001 \
  -H "Authorization: Bearer <access_token>"

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "rep_001",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "reportType": "SAR",
    "reportNumber": "SAR-2026-00001",
    "title": "Structuring Pattern — 4 Deposits in 3 Hours",
    "status": "APPROVED",
    "xmlContent": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Report>...</Report>",
    "jsonData": {
      "caseId": "case_12345abcde",
      "transactionIds": ["tx_abc123def456"],
      "suspicionType": "STRUCTURING"
    },
    "relatedCaseId": "case_12345abcde",
    "generatedBy": "550e8400-e29b-41d4-a716-446655440000",
    "approvedBy": "550e8400-e29b-41d4-a716-446655440000",
    "filedAt": null,
    "createdAt": "2026-05-16T11:00:00Z",
    "updatedAt": "2026-05-16T14:00:00Z"
  }
}

Get Report XML

Download the CBN-compliant XML representation of a report. Path Parameters

Parameter	Type	Description
`id`	`string`	Report UUID

Example Request

curl -X GET /v1/reports/rep_001/xml \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/xml"

Example Response — 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<Report xmlns="http://www.cbn.gov.ng/aml">
  <ReportType>SAR</ReportType>
  <ReportId>SAR-2026-00001</ReportId>
  <SubmissionDate>2026-05-16</SubmissionDate>
  <Institution>First Bank of Nigeria</Institution>
  <Subject>
    <CustomerId>cust_001</CustomerId>
    <TransactionIds>
      <Id>tx_abc123def456</Id>
      <Id>tx_def789ghi012</Id>
    </TransactionIds>
  </Subject>
  <Narrative>Customer made 4 deposits totaling ₦4.8M in 3 hours...</Narrative>
</Report>

The XML format follows CBN regulatory specifications. Approved reports can be submitted directly through the CBN portal.

Approve Report

Mark a report as approved for regulatory submission. Path Parameters

Parameter	Type	Description
`id`	`string`	Report UUID

Request Body

Field	Type	Required	Description
`approverNotes`	`string`		Optional review notes

Example Request

curl -X PATCH /v1/reports/rep_001/approve \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "approverNotes": "Verified against case files. Ready for CBN submission."
  }'

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "rep_001",
    "status": "APPROVED",
    "approvedBy": "550e8400-e29b-41d4-a716-446655440000",
    "updatedAt": "2026-05-16T14:00:00Z"
  }
}

Once approved, a report cannot be modified. If errors are discovered, create a new amended report referencing the original.

File Report

Mark a report as officially filed with the CBN. Path Parameters

Parameter	Type	Description
`id`	`string`	Report UUID

Example Request

curl -X PATCH /v1/reports/rep_001/file \
  -H "Authorization: Bearer <access_token>"

Example Response — 200 OK

{
  "success": true,
  "data": {
    "id": "rep_001",
    "status": "FILED",
    "filedAt": "2026-05-16T15:00:00Z",
    "updatedAt": "2026-05-16T15:00:00Z"
  }
}

Overview

Core Concepts

Features

Modules

API Reference

Overview

Common Workflows

Permissions

Report Types

Report Statuses

Endpoints

Generate SAR

Generate CTR

Generate FTR

List Reports

Get Report Detail

Get Report XML

Approve Report

File Report

Overview

Core Concepts

Features

Modules

API Reference

Documentation Index

​Overview

​Common Workflows

​Permissions

​Report Types

​Report Statuses

​Endpoints

​Generate SAR

​Generate CTR

​Generate FTR

​List Reports

​Get Report Detail

​Get Report XML

​Approve Report

​File Report

Overview

Common Workflows

Permissions

Report Types

Report Statuses

Endpoints

Generate SAR

Generate CTR

Generate FTR

List Reports

Get Report Detail

Get Report XML

Approve Report

File Report