Transaction Monitoring API Reference

Transaction Monitoring API Reference

Complete API reference for integrating with Loci's transaction monitoring and fraud decisioning layer.

This reference is generated from the Loci Developer Integration Guide Postman collection. It includes authentication, transaction scoring, entity risk intelligence, custom data tables, transaction review, alert queues, and rule listing endpoints.

Base URL

https://api.runloci.com

Authentication

Most endpoints require both headers:

  • x-org-id: your Loci organization ID
  • x-api-key: your Loci API key
For operator-console endpoints, a bearer token may also be used where enabled.

Last updated from Postman collection v0.8.

Version 1.0.0 Base URL: https://api.runloci.com

Authentication

x-api-key

Type: API Key (in header)

Loci API key for server-side integrations.

x-org-id

Type: API Key (in header)

Loci organization identifier for tenant routing.

1. Setup & Authentication

Authentication

All Loci API requests require two headers:

x-api-key: your_api_key_here
x-org-id: your_org_id_here

Security Best Practices

✅ DO:

  • Store credentials in environment variables
  • Use HTTPS for all requests
  • Rotate API keys quarterly
  • Implement request signing for production

❌ DON'T:

  • Hard-code credentials in code
  • Share API keys across environments
  • Log API keys in application logs
POST/auth/validate-org

Test Authentication

Test your API credentials and connectivity to Loci.

Expected Response:

{
  "status": "success",
  "data": {
    "transactionsMonitored": 12345,
    "highRiskAlerts": 89,
    "deployedRules": 15
  }
}

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "org_id": "{{orgId}}",
  "api_key": "{{apiKey}}"
}

Responses

200Successful response

2. Transaction Scoring

Real-Time Transaction Scoring

The primary real-time endpoint for transaction risk evaluation. Client systems decide how to apply the returned decision according to their operating policy.

Operating Notes

This endpoint is designed for real-time transaction decisions. Confirm production latency, availability, and rate-limit commitments in the deployment agreement for your tenant.

Integration Pattern

javascript
// 1. Score transaction
const decision = await loci.scoreTransaction(tx);
// 2. Take action
switch (decision.decision) {
  case 'approve':
    await settleTx(tx);
    break;
  case 'review':
    await queueForReview(tx);
    break;
  case 'decline':
    await blockTx(tx);
    break;
}

Understanding Fraud Scores

Fraud scores are normalized to a 0-100 range. Higher scores indicate higher risk, and responses include matched rules and supporting evidence where available.

POST/v1/transaction/{{orgId}}

Process Transaction - Approve

Transaction Scoring - The Hot Path

Submit transactions for real-time fraud detection.

Response Format

{
  "success": true,
  "decision": "approve|review|decline",
  "fraud_score": 0-100,
  "explanations": []
}

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "transaction_id": "TXN_{{$randomInt}}",
  "entity_id": "USER_001",
  "amount": 5000,
  "currency": "NGN",
  "transaction_date": "2025-10-11",
  "transaction_time": "10:30:00Z",
  "transaction_type": "TRANSFER",
  "description": "Low-risk payment",
  "source_account_number": "1234567890",
  "source_bank_code": "044",
  "source_account_name": "John Doe",
  "beneficiary_account_number": "0987654321",
  "beneficiary_account_name": "Jane Smith",
  "beneficiary_bank_code": "058",
  "pep": false,
  "direction": "outgoing"
}

Responses

200Successful response
POST/v1/transaction/{{orgId}}

Process Transaction - Review

Medium-risk transaction example.

Expected fraud score: 15-79
Expected decision: review

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "transaction_id": "TXN_{{$randomInt}}",
  "entity_id": "USER_002",
  "amount": 75000,
  "currency": "NGN",
  "transaction_date": "2025-10-11",
  "transaction_time": "10:30:00Z",
  "transaction_type": "TRANSFER",
  "description": "First transaction to new beneficiary",
  "source_account_number": "1234567890",
  "beneficiary_account_number": "9999888877",
  "beneficiary_bank_code": "011",
  "pep": false,
  "direction": "outgoing"
}

Responses

200Successful response
POST/v1/transaction/{{orgId}}

Process Transaction - Decline

High-risk transaction example.

Expected fraud score: >= 80
Expected decision: decline

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "transaction_id": "TXN_{{$randomInt}}",
  "entity_id": "USER_003",
  "amount": 250000,
  "currency": "NGN",
  "transaction_date": "2025-10-11",
  "transaction_time": "10:30:00Z",
  "transaction_type": "TRANSFER",
  "description": "Urgent payment",
  "beneficiary_account_number": "5555555555",
  "beneficiary_is_cross_border": true,
  "pep": false,
  "direction": "outgoing"
}

Responses

200Successful response

3. Entity Risk Intelligence

Entity Risk Intelligence

Understand risk profile and network position through graph analytics.

Why Network Intelligence Matters

Traditional fraud detection looks at transactions in isolation. Loci's network intelligence reveals:

  • Fraud Rings: Coordinated networks of compromised accounts
  • Money Mule Networks: Layering and cash-out operations
  • Hub Behavior: Entities facilitating multiple suspicious flows

Integration Patterns

javascript
// Onboarding Screening
const risk = await loci.getEntityCentrality(userId);
if (risk.riskLevel === 'critical') {
  return { approved: false };
}
// Dynamic Transaction Limits
const limit = baseLimit * (1 - risk.centrality.score);
GET/entities/{{entity_id}}/centrality?startDate=2025-09-01&endDate=2025-10-11

Get Entity Centrality Score

Entity Centrality Scoring

Get network position and risk profile for a specific entity.

What is Centrality?

Measures how influential or connected an entity is within your transaction network.

Response Metrics

  • true_degree_centrality: Normalized score (0-1)
  • unique_neighbors: Number of unique counterparties
  • risk_assessment: Overall risk score and label

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
startDatequerystring—
endDatequerystring—

Responses

200Successful response
GET/entities/{{entity_id}}/graph?direction=both&depth=2&edgeMode=collapsed

Get Entity Graph

Retrieve transaction network graph for visualization and analysis.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
directionquerystring—
depthquerystring—
edgeModequerystring—

Responses

200Successful response
POST/entities/{{entity_id}}/export

Export Entity Case Bundle

Export complete network intelligence as ZIP file for investigation.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "format": "casebundle_v1",
  "graphParams": {
    "direction": "both",
    "depth": 2,
    "edgeMode": "collapsed"
  },
  "includePII": false,
  "maxNodes": 500,
  "maxEdges": 2000
}

Responses

200Successful response

4. Data Management

Managing Contextual Data

Loci's FLM rules can reference custom data tables.

Common Table Types

Table TypeSchema ExampleRule Usage
Blocklist{entity_id, reason, blocked_at}Instant decline
Allowlist{entity_id, tier, expires_at}Skip checks
Merchant Categories{merchant_id, category, risk}Category rules
VIP Customers{entity_id, tier, limit_override}Relaxed monitoring
POST/v1/tables/{{orgId}}

Create Data Table

Create custom data tables for FLM rules (blocklists, allowlists, etc.).

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "tableName": "blocklist",
  "columns": [
    {
      "name": "entry_id",
      "columnType": "TEXT"
    },
    {
      "name": "category",
      "columnType": "TEXT"
    },
    {
      "name": "reference",
      "columnType": "TEXT"
    },
    {
      "name": "risk_level",
      "columnType": "TEXT"
    },
    {
      "name": "source",
      "columnType": "TEXT"
    },
    {
      "name": "created_at",
      "columnType": "TIMESTAMP"
    },
    {
      "name": "last_updated",
      "columnType": "DATE"
    },
    {
      "name": "expiry_date",
      "columnType": "TIMESTAMP"
    },
    {
      "name": "notes",
      "columnType": "TEXT"
    }
  ]
}

Responses

200Successful response
PUT/v1/tables/{{orgId}}/:TABLENAME/data

Add Data to Table

Insert rows into a data table.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

[
  {
    "item_id": "LIST-0001",
    "full_name": "Sample Person One",
    "aliases": "Sample Alias One",
    "date_of_birth": "1970-01-01",
    "nationality": "Sample Country",
    "list_program": "Sample Watchlist",
    "risk_level": "High",
    "status": "Active",
    "last_updated": "2026-01-01",
    "notes": "Illustrative sample record."
  },
  {
    "item_id": "LIST-0002",
    "full_name": "Sample Organization Two",
    "aliases": "Sample Alias Two",
    "nationality": "Sample Country",
    "list_program": "Sample Watchlist",
    "risk_level": "Medium",
    "status": "Active",
    "last_updated": "2026-01-01",
    "notes": "Illustrative sample record."
  }
]

Responses

200Successful response

5. Transaction Management

Transaction Management

Manage transactions throughout their lifecycle.

Transaction States

Initial Scoring
       ↓
   ┌───────────┬──────────────┬──────────┐
   ↓           ↓              ↓          ↓
Approve     Review        Decline   (Manual)
 (Auto)    (Queue)         (Auto)   Override
   ↓           ↓              ↓          ↓
Settled   Investigated   Blocked   Approved/
                ↓                   Fraud
          ┌─────┴─────┐
          ↓           ↓
      Approved    Confirmed
                   Fraud
GET/v1/transactions?limit=25&flagged=true

List Transactions

Retrieve transactions with filtering and pagination.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
limitquerystring—
flaggedquerystring—

Responses

200Successful response
GET/v1/transactions/trn_abc123

Get Transaction Details

Retrieve full details for a specific transaction.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Responses

200Successful response
PATCH/v1/transactions/trn_abc123/approve

Approve Transaction

Manually approve a flagged transaction after review.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "notes": "Verified with customer via phone. Legitimate transaction."
}

Responses

200Successful response
PATCH/v1/transactions/trn_abc123/fraud

Mark as Fraud

Confirm a transaction as fraudulent after investigation.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Request Body

Content-Type: application/json

{
  "risk_level": "high",
  "notes": "Confirmed fraud via customer report and chargeback.",
  "team": [
    "analyst_001"
  ]
}

Responses

200Successful response
GET/v1/transactions/search?q=account_number&page=1&limit=25

Search Transactions

Full-text search across all transaction fields.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
qquerystring—
pagequerystring—
limitquerystring—

Responses

200Successful response

6. Advanced Features

Advanced Features

Advanced analytics and operational tools.

GET/entities/{{entity_id}}/beneficiaries?direction=outgoing&from=2025-09-01&to=2025-10-11&orderBy=amount

Get Entity Beneficiaries

Analyze entity's top counterparties by volume or count.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
directionquerystring—
fromquerystring—
toquerystring—
orderByquerystring—

Responses

200Successful response
GET/v1/org/{{orgId}}/alert-queues

Get Alert Queues

Get counts for fraud operations queues.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—

Responses

200Successful response

7. Testing & Monitoring

Testing & Monitoring

Tools for testing integration and monitoring system health.

GET/v1/rules/{{orgId}}?limit=20

List Active Rules

Retrieve all FLM rules deployed for your organization.

Parameters

NameLocationTypeDescription
x-api-keyheaderstring—
x-org-idheaderstring—
limitquerystring—

Responses

200Successful response