> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> Generate and manage regulatory reports required by the Central Bank of Nigeria

## 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**

```bash theme={null}
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**

```json theme={null}
{
  "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**

```bash theme={null}
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**

```json theme={null}
{
  "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**

```bash theme={null}
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**

```json theme={null}
{
  "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**

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

**Example Response -200 OK**

```json theme={null}
{
  "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**

```bash theme={null}
curl -X GET /v1/reports/rep_001 \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "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**

```bash theme={null}
curl -X GET /v1/reports/rep_001/xml \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/xml"
```

**Example Response -200 OK**

```xml theme={null}
<?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>
```

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

***

### 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**

```bash theme={null}
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**

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

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

***

### File Report

Mark a report as officially filed with the CBN.

**Path Parameters**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | Report UUID |

**Example Request**

```bash theme={null}
curl -X PATCH /v1/reports/rep_001/file \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

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