AML API Documentation

Quick Start

The BizFirstFi AML API provides comprehensive access to transaction monitoring, case management, and regulatory reporting functionality.

Base URL

https://api.bizfirstfi.com/aml/v1

Development: http://localhost:5001/api/aml

Authentication

API uses Bearer token authentication

Authorization: Bearer <your-api-token>

Content Type

All requests should include:

Content-Type: application/json

Open Interactive API Docs (Swagger)

Transaction Monitoring Endpoints

POST /transactions/monitor

Submit transactions for real-time AML monitoring and analysis

Parameter	Type	Required	Description
transactionId	string	Yes	Unique transaction identifier
customerId	string	Yes	Customer account identifier
amount	decimal	Yes	Transaction amount
currency	string	Yes	ISO 4217 currency code
transactionType	string	Yes	Type: WIRE, ACH, CASH, CHECK, CARD
counterparty	object	No	Counterparty information

Request Example:
POST /api/aml/transactions/monitor
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "transactionId": "txn-789012",
  "customerId": "cust-456",
  "amount": 15000.00,
  "currency": "USD",
  "transactionType": "WIRE",
  "transactionDate": "2025-08-21T14:30:00Z",
  "originCountry": "US",
  "destinationCountry": "CH",
  "counterparty": {
    "name": "Swiss Bank AG",
    "accountNumber": "CH93 0076 2011 6238 5295 7",
    "address": "Zurich, Switzerland"
  },
  "description": "International wire transfer"
}

Response Example:
{
  "transactionId": "txn-789012",
  "monitoringResult": {
    "riskScore": 75,
    "riskLevel": "High",
    "alertGenerated": true,
    "alertId": "alert-001234",
    "triggeredScenarios": [
      "HIGH_RISK_GEOGRAPHY",
      "LARGE_WIRE_TRANSFER"
    ]
  },
  "processedAt": "2025-08-21T14:30:05Z"
}
                

GET /transactions/{id}/analysis

Retrieve detailed analysis for a specific transaction

Request Example:
GET /api/aml/transactions/txn-789012/analysis
Authorization: Bearer <your-token>

Response Example:
{
  "transactionId": "txn-789012",
  "analysis": {
    "riskScore": 75,
    "riskFactors": [
      {
        "factor": "Geographic Risk",
        "score": 30,
        "description": "Transaction involves high-risk jurisdiction"
      },
      {
        "factor": "Amount Risk",
        "score": 25,
        "description": "Large transaction amount"
      },
      {
        "factor": "Pattern Risk",
        "score": 20,
        "description": "Unusual for customer profile"
      }
    ],
    "networkAnalysis": {
      "connectedEntities": 3,
      "suspiciousConnections": 1,
      "riskNetwork": false
    },
    "recommendedAction": "MANUAL_REVIEW"
  }
}
                

Alert Management Endpoints

GET /alerts

Retrieve list of AML alerts with filtering and pagination

Query Parameter	Type	Description
status	string	Filter by status (Open, InProgress, Closed, Escalated)
priority	string	Filter by priority (High, Medium, Low)
assignedTo	string	Filter by assigned analyst ID
scenario	string	Filter by triggering scenario type
dateFrom	datetime	Filter alerts created after this date
dateTo	datetime	Filter alerts created before this date

Request Example:
GET /api/aml/alerts?status=Open&priority=High&limit=20
Authorization: Bearer <your-token>

Response Example:
{
  "data": [
    {
      "alertId": "alert-001234",
      "customerId": "cust-456",
      "status": "Open",
      "priority": "High",
      "riskScore": 85,
      "scenario": "STRUCTURING",
      "createdAt": "2025-08-21T14:30:00Z",
      "assignedTo": "analyst-001",
      "slaDeadline": "2025-08-22T14:30:00Z",
      "transactionCount": 5,
      "totalAmount": 45000.00
    }
  ],
  "pagination": {
    "total": 127,
    "page": 1,
    "limit": 20,
    "totalPages": 7
  }
}
                

POST /alerts/{id}/assign

Assign alert to an analyst for investigation

Request Example:
POST /api/aml/alerts/alert-001234/assign
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "analystId": "analyst-002",
  "priority": "High",
  "notes": "High-value structuring pattern detected"
}

Response Example:
{
  "alertId": "alert-001234",
  "status": "InProgress",
  "assignedTo": "analyst-002",
  "assignedAt": "2025-08-21T15:00:00Z",
  "slaDeadline": "2025-08-22T15:00:00Z"
}
                

PUT /alerts/{id}/investigation

Update investigation progress and add notes

Request Example:
PUT /api/aml/alerts/alert-001234/investigation
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "status": "UnderInvestigation",
  "investigationNotes": "Reviewed customer profile and transaction history. Pattern consistent with structuring behavior. Gathering additional evidence.",
  "nextSteps": "Contact customer for explanation of transaction pattern",
  "evidenceCollected": [
    "Transaction timeline analysis",
    "Customer account history",
    "Similar pattern detection"
  ]
}

Response Example:
{
  "alertId": "alert-001234",
  "status": "UnderInvestigation",
  "lastUpdated": "2025-08-21T16:15:00Z",
  "investigationProgress": 65
}
                

Case Management Endpoints

POST /cases

Create new AML case from one or more alerts

Request Example:
POST /api/aml/cases
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "customerId": "cust-456",
  "alertIds": ["alert-001234", "alert-001235"],
  "caseType": "STRUCTURING",
  "priority": "High",
  "summary": "Multiple structuring alerts for customer showing pattern of transactions just below CTR threshold",
  "assignedOfficer": "officer-001"
}

Response Example:
{
  "caseId": "case-789",
  "customerId": "cust-456",
  "status": "Open",
  "priority": "High",
  "createdAt": "2025-08-21T16:30:00Z",
  "assignedOfficer": "officer-001",
  "slaDeadline": "2025-08-26T16:30:00Z",
  "alertCount": 2,
  "totalExposure": 45000.00
}
                

GET /cases/{id}

Retrieve detailed case information

Request Example:
GET /api/aml/cases/case-789
Authorization: Bearer <your-token>

Response Example:
{
  "caseId": "case-789",
  "customerId": "cust-456",
  "status": "Open",
  "priority": "High",
  "caseType": "STRUCTURING",
  "createdAt": "2025-08-21T16:30:00Z",
  "assignedOfficer": "officer-001",
  "summary": "Multiple structuring alerts...",
  "alerts": [
    {
      "alertId": "alert-001234",
      "scenario": "STRUCTURING",
      "amount": 25000.00,
      "createdAt": "2025-08-21T14:30:00Z"
    }
  ],
  "investigation": {
    "status": "InProgress",
    "findings": "Customer exhibits pattern consistent with structuring",
    "evidence": ["Transaction analysis", "Customer interview"],
    "recommendation": "FILE_SAR"
  },
  "timeline": [
    {
      "timestamp": "2025-08-21T16:30:00Z",
      "action": "Case Created",
      "user": "system",
      "details": "Consolidated from 2 alerts"
    }
  ]
}
                

PUT /cases/{id}/decision

Make final decision on AML case

Request Example:
PUT /api/aml/cases/case-789/decision
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "decision": "FILE_SAR",
  "reasoning": "Transactions show clear pattern of structuring with no legitimate business purpose",
  "sarRequired": true,
  "confidenceLevel": "High",
  "reviewedBy": "officer-001",
  "approvedBy": "manager-001"
}

Response Example:
{
  "caseId": "case-789",
  "status": "Closed",
  "decision": "FILE_SAR",
  "closedAt": "2025-08-21T17:45:00Z",
  "sarFiling": {
    "sarId": "sar-2025-001234",
    "filingDeadline": "2025-09-20T23:59:59Z",
    "status": "Pending"
  }
}
                

Regulatory Reporting Endpoints

POST /reports/sar

Generate and submit Suspicious Activity Report (SAR)

Request Example:
POST /api/aml/reports/sar
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "caseId": "case-789",
  "suspiciousActivity": {
    "type": "STRUCTURING",
    "description": "Customer conducted multiple cash deposits just below $10,000 threshold over 30-day period",
    "amountInvolved": 45000.00,
    "dateRange": {
      "from": "2025-07-15",
      "to": "2025-08-15"
    }
  },
  "subjectInformation": {
    "customerId": "cust-456",
    "role": "SUBJECT",
    "relationship": "CUSTOMER"
  },
  "filingInstitution": {
    "name": "Demo Bank",
    "ein": "12-3456789",
    "address": "123 Main St, City, State 12345"
  }
}

Response Example:
{
  "sarId": "sar-2025-001234",
  "bsaId": "2025123456789012",
  "filingStatus": "Submitted",
  "submittedAt": "2025-08-21T18:00:00Z",
  "acknowledgment": "ACK-2025-001234"
}
                

GET /reports/sar/{id}

Retrieve SAR filing details and status

Request Example:
GET /api/aml/reports/sar/sar-2025-001234
Authorization: Bearer <your-token>

Response Example:
{
  "sarId": "sar-2025-001234",
  "bsaId": "2025123456789012",
  "caseId": "case-789",
  "filingStatus": "Accepted",
  "submittedAt": "2025-08-21T18:00:00Z",
  "acceptedAt": "2025-08-21T18:15:00Z",
  "narrative": "Subject conducted 5 cash deposits...",
  "totalAmount": 45000.00,
  "acknowledgment": "ACK-2025-001234"
}
                

Customer Risk Management

GET /customers/{id}/risk-profile

Retrieve customer risk assessment and profile

Request Example:
GET /api/aml/customers/cust-456/risk-profile
Authorization: Bearer <your-token>

Response Example:
{
  "customerId": "cust-456",
  "riskProfile": {
    "overallRiskLevel": "High",
    "riskScore": 75,
    "lastAssessed": "2025-08-21T12:00:00Z",
    "factors": [
      {
        "category": "Geographic",
        "risk": "Medium",
        "score": 25,
        "reason": "Transactions with moderate-risk countries"
      },
      {
        "category": "Transaction Pattern",
        "risk": "High", 
        "score": 35,
        "reason": "Unusual transaction patterns detected"
      },
      {
        "category": "Industry",
        "risk": "Low",
        "score": 15,
        "reason": "Low-risk industry classification"
      }
    ]
  },
  "alertHistory": {
    "totalAlerts": 12,
    "last90Days": 5,
    "sarFilings": 1
  },
  "monitoring": {
    "enhancedDueDiligence": true,
    "reviewFrequency": "Monthly",
    "nextReview": "2025-09-21"
  }
}
                

PUT /customers/{id}/risk-profile

Update customer risk assessment

Request Example:
PUT /api/aml/customers/cust-456/risk-profile
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "riskLevel": "High",
  "enhancedDueDiligence": true,
  "reviewFrequency": "Monthly",
  "notes": "Customer profile updated due to suspicious transaction patterns",
  "reviewedBy": "officer-001"
}

Response Example:
{
  "customerId": "cust-456",
  "riskLevel": "High",
  "updatedAt": "2025-08-21T18:30:00Z",
  "updatedBy": "officer-001",
  "nextReview": "2025-09-21T18:30:00Z"
}
                

Error Handling

Status Code	Description	Common Causes
400	Bad Request	Invalid transaction data, missing required fields
401	Unauthorized	Invalid or missing authentication token
403	Forbidden	Insufficient permissions for AML operations
404	Not Found	Alert, case, or customer not found
422	Unprocessable Entity	Business rule violation, invalid state transition
429	Too Many Requests	Rate limit exceeded for monitoring submissions

Error Response Format

{
  "error": {
    "code": "INVALID_TRANSACTION_DATA",
    "message": "Transaction amount must be greater than zero",
    "details": [
      {
        "field": "amount",
        "error": "Must be a positive decimal value"
      }
    ]
  },
  "timestamp": "2025-08-21T18:00:00Z",
  "requestId": "req-aml-12345"
}
                

Rate Limiting

Endpoint Category	Rate Limit	Time Window
Transaction Monitoring	1,000 requests	Per minute
Alert Management	500 requests	Per minute
Case Operations	200 requests	Per minute
Reporting	50 requests	Per minute