Back to Developer Hub
OpenAPI 3.0

API Reference

Complete REST API documentation powered by OpenAPI

Download Spec
Base URL: https://api.elysium-nexus.com/v1
Auth: Authorization: Bearer ely_sk_...
Format: JSON

API Key: All requests require an API key in the Authorization header. Tenant identity is derived from the API key. See Authentication for details.

API Sections

CustomersAccountsTransactionsBHINBAFraudKYC-AMLWorkflowsReportsSync
redocly logoAPI docs by Redocly

Elysium Nexus API (1.0.0)

Download OpenAPI specification:Download

License: Proprietary

API for Elysium Nexus - AI-powered business health monitoring and insights platform.

Authentication

All requests require a Bearer token:

Authorization: Bearer ely_sk_<your-api-key>

Tenant identity is derived from the API key. The x-tenant-id header is deprecated and should not be used.

Services

  • Unified Data Service (port 4001): Customer, Account, Transaction data
  • Insights Service (port 3005): BHI, NBA, Reports, Workflows

Tenants

Tenant identity operations

Get current tenant identity

Returns the tenant ID associated with the authenticated API key.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
tenantId
required
string <uuid>

Response samples

Content type
application/json
{
  • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
}

Customers

Customer management

List customers

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
search
string

Search by name or email

status
string
Enum: "active" "inactive" "suspended" "closed"
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (Customer)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

Get customer by ID

Authorizations:
BearerAuth
path Parameters
customerId
required
string <uuid>
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object (Customer)

Response samples

Content type
application/json
{
  • "success": true,
  • "customer": {
    }
}

Accounts

Account management

List accounts

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
customerId
string <uuid>
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (Account)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

Transactions

Transaction management

List transactions

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
customerId
string <uuid>
accountId
string <uuid>
type
string
Enum: "credit" "debit"
startDate
string <date-time>
endDate
string <date-time>
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (Transaction)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

Sync

Data synchronization

Trigger data sync

Authorizations:
BearerAuth
path Parameters
connectorType
required
string
Value: "core_banking"
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object

Response samples

Content type
application/json
{
  • "success": true,
  • "syncStatus": {
    }
}

BHI

Business Health Index

List BHI records

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
customerId
string <uuid>
bhiBand
string
Enum: "excellent" "good" "fair" "poor" "critical"
trend
string
Enum: "improving" "stable" "declining" "volatile"
isLatest
boolean
Default: true
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (BHIRecord)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "pagination": {
    }
}

Calculate BHI from database

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
customerId
string <uuid>
customerIds
Array of strings <uuid> [ items <uuid > ]
object (BHIWeights)

Responses

Response Schema: application/json
success
boolean
Array of objects (BHICalculationResult)
object

Request samples

Content type
application/json
{
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "customerIds": [
    ],
  • "weights": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "results": [
    ],
  • "summary": {
    }
}

Get customer BHI

Authorizations:
BearerAuth
path Parameters
customerId
required
string <uuid>
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object (BHIRecord)

Response samples

Content type
application/json
{
  • "success": true,
  • "bhi": {
    }
}

Get BHI history

Authorizations:
BearerAuth
path Parameters
customerId
required
string <uuid>
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
customerId
string
Array of objects (BHIHistoryRecord)
object (Pagination)

Response samples

Content type
application/json
{
  • "success": true,
  • "customerId": "string",
  • "history": [
    ],
  • "pagination": {
    }
}

Get portfolio summary

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object (BHISummary)

Response samples

Content type
application/json
{
  • "success": true,
  • "summary": {
    }
}

NBA

Next-Best-Action recommendations

Generate Next-Best-Actions

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
customerId
required
string <uuid>
object

Responses

Response Schema: application/json
success
boolean
Array of objects (NBAAction)
evaluatedRules
integer
matchedRules
integer

Request samples

Content type
application/json
{
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "bhi": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "actions": [
    ],
  • "evaluatedRules": 0,
  • "matchedRules": 0
}

Workflows

Workflow automation

List workflows

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (Workflow)
total
integer

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total": 0
}

Trigger workflow

Authorizations:
BearerAuth
path Parameters
workflowId
required
string
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
customerId
string <uuid>

Responses

Response Schema: application/json
success
boolean
runId
string
status
string
message
string

Request samples

Content type
application/json
{
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "runId": "string",
  • "status": "string",
  • "message": "string"
}

List workflow runs

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
workflowId
string
status
string
Enum: "pending" "running" "succeeded" "failed"
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (WorkflowRun)
total
integer

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total": 0
}

Reports

Report generation

Generate customer BHI report

Authorizations:
BearerAuth
path Parameters
customerId
required
string <uuid>
query Parameters
format
string
Default: "json"
Enum: "json" "csv" "pdf"
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema:
object

Response samples

Content type
{ }

Generate portfolio BHI report

Authorizations:
BearerAuth
query Parameters
format
string
Default: "json"
Enum: "json" "csv" "pdf"
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema:
object

Response samples

Content type
{ }

Fraud

Advisory fraud signal detection. IMPORTANT: These endpoints produce advisory signals only. They do NOT block transactions, do NOT guarantee fraud detection, and require human review before any action. All signals are rule-based and deterministic.

List available fraud signal definitions

Returns all available fraud signal definitions. These define what patterns the system can detect. ADVISORY ONLY - does not block transactions.

Authorizations:
BearerAuth
query Parameters
enabledOnly
boolean
Default: true

Only return enabled signals

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (SignalDefinition)
totalCount
integer
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "signals": [
    ],
  • "totalCount": 0,
  • "disclaimer": "string"
}

Evaluate fraud signals for an entity

Evaluates fraud signals for a specific entity (customer, account, agent, or merchant).

IMPORTANT: This produces ADVISORY signals only. It does NOT:

  • Block or interdict transactions
  • Make automated decisions
  • Guarantee fraud detection or loss prevention

All results require human review before any action.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
entityType
required
string (EvaluableEntityType)
Enum: "customer" "account" "agent" "merchant"
entityId
required
string
windowDays
integer [ 1 .. 365 ]
Default: 30
signalIds
Array of strings

Specific signals to run (optional - runs all applicable if omitted)

Responses

Response Schema: application/json
success
boolean
object (FraudAlert)

Advisory fraud alert - requires human review before any action. The isAdvisoryOnly field is always true to emphasize this is not a blocking decision.

disclaimer
string

Reminder that this is advisory only

Request samples

Content type
application/json
{
  • "entityType": "customer",
  • "entityId": "string",
  • "windowDays": 30,
  • "signalIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "alert": {
    },
  • "disclaimer": "string"
}

List fraud alerts (computed on-demand)

Currently returns empty as alerts are computed on-demand via POST /fraud/evaluate. Persistent alert storage is planned for future implementation.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (FraudAlert)
message
string
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "alerts": [
    ],
  • "message": "string",
  • "disclaimer": "string"
}

List fraud cases

List fraud cases with filtering and pagination. Cases are immutable records created from fraud alerts for compliance review.

Authorizations:
BearerAuth
query Parameters
entityType
string
Enum: "customer" "account" "agent" "merchant"

Filter by entity type

entityId
string

Filter by entity ID

severity
string

Filter by severity (comma-separated for multiple)

status
string

Filter by status (comma-separated for multiple)

minScore
number

Minimum fraud score

maxScore
number

Maximum fraud score

startDate
string <date-time>

Filter cases created after this date

endDate
string <date-time>

Filter cases created before this date

limit
integer <= 500
Default: 50
offset
integer
Default: 0
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (FraudCase)
total
integer
limit
integer
offset
integer
hasMore
boolean
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "hasMore": true,
  • "disclaimer": "string"
}

Create a fraud case

Create a new fraud case from a fraud alert.

IMPORTANT: Fraud cases are APPEND-ONLY and IMMUTABLE for audit compliance. Once created, case data cannot be modified - only events can be added.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
alertId
required
string <uuid>
entityType
required
string (EvaluableEntityType)
Enum: "customer" "account" "agent" "merchant"
entityId
required
string
severity
required
string (FraudCaseSeverity)
Enum: "low" "medium" "high" "critical"

Severity classification for fraud cases

overallScore
required
number [ 0 .. 100 ]
title
string
summary
string
triggeredSignals
Array of objects
explainability
object
windowDays
integer
Default: 30
windowStart
string <date-time>
windowEnd
string <date-time>
metadata
object

Responses

Response Schema: application/json
success
boolean
object (FraudCase)

Immutable fraud case record for compliance review. Cases are append-only - changes are recorded via events.

disclaimer
string

Request samples

Content type
application/json
{
  • "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  • "entityType": "customer",
  • "entityId": "string",
  • "severity": "low",
  • "overallScore": 100,
  • "title": "string",
  • "summary": "string",
  • "triggeredSignals": [
    ],
  • "explainability": { },
  • "windowDays": 30,
  • "windowStart": "2019-08-24T14:15:22Z",
  • "windowEnd": "2019-08-24T14:15:22Z",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "case": {
    },
  • "disclaimer": "string"
}

Get fraud case statistics

Get aggregate statistics for fraud cases in the tenant.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "stats": {
    },
  • "disclaimer": "string"
}

Get a fraud case with events

Get a specific fraud case by ID including all audit events.

Authorizations:
BearerAuth
path Parameters
caseId
required
string <uuid>

The fraud case ID

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object

Immutable fraud case record for compliance review. Cases are append-only - changes are recorded via events.

disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "case": {
    },
  • "disclaimer": "string"
}

List events for a fraud case

Get the audit event log for a specific fraud case.

Authorizations:
BearerAuth
path Parameters
caseId
required
string <uuid>

The fraud case ID

query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
caseId
string <uuid>
Array of objects (FraudCaseEvent)
total
integer
limit
integer
offset
integer
hasMore
boolean

Response samples

Content type
application/json
{
  • "success": true,
  • "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  • "data": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "hasMore": true
}

Add an event to a fraud case

Add an event to a fraud case (append-only). This is the primary method for recording changes to a case. Supports: status_changed, assigned, note_added, evidence_added, closed

Authorizations:
BearerAuth
path Parameters
caseId
required
string <uuid>

The fraud case ID

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
eventType
required
string (FraudCaseEventType)
Enum: "created" "status_changed" "assigned" "unassigned" "note_added" "evidence_added" "escalated" "closed"

Type of fraud case event

actorType
required
string
Enum: "user" "system" "workflow"
actorId
required
string
actorName
string
newStatus
string (FraudCaseStatus)
Enum: "open" "under_review" "pending_info" "escalated" "closed_cleared" "closed_suspicious" "closed_reported"

Status of a fraud case:

  • open: Newly created, awaiting review
  • under_review: Analyst actively reviewing
  • pending_info: Waiting for additional information
  • escalated: Escalated to senior reviewer
  • closed_cleared: Reviewed and determined not suspicious
  • closed_suspicious: Reviewed and confirmed suspicious
  • closed_reported: Reported to authorities/filed SAR
assigneeId
string
assigneeName
string
noteContent
string
noteType
string
evidenceType
string
evidenceReference
object
resolution
object

Responses

Response Schema: application/json
success
boolean
object (FraudCaseEvent)

Immutable event in fraud case audit log

Request samples

Content type
application/json
{
  • "eventType": "created",
  • "actorType": "user",
  • "actorId": "string",
  • "actorName": "string",
  • "newStatus": "open",
  • "assigneeId": "string",
  • "assigneeName": "string",
  • "noteContent": "string",
  • "noteType": "string",
  • "evidenceType": "string",
  • "evidenceReference": { },
  • "resolution": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "event": {
    }
}

Change fraud case status

Convenience endpoint to change case status via event.

Authorizations:
BearerAuth
path Parameters
caseId
required
string <uuid>

The fraud case ID

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
newStatus
required
string (FraudCaseStatus)
Enum: "open" "under_review" "pending_info" "escalated" "closed_cleared" "closed_suspicious" "closed_reported"

Status of a fraud case:

  • open: Newly created, awaiting review
  • under_review: Analyst actively reviewing
  • pending_info: Waiting for additional information
  • escalated: Escalated to senior reviewer
  • closed_cleared: Reviewed and determined not suspicious
  • closed_suspicious: Reviewed and confirmed suspicious
  • closed_reported: Reported to authorities/filed SAR
actorId
required
string
actorName
string
actorType
string
Default: "user"
Enum: "user" "system" "workflow"

Responses

Response Schema: application/json
success
boolean
object (FraudCaseEvent)

Immutable event in fraud case audit log

Request samples

Content type
application/json
{
  • "newStatus": "open",
  • "actorId": "string",
  • "actorName": "string",
  • "actorType": "user"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "event": {
    }
}

Add a note to a fraud case

Convenience endpoint to add a review note to a case.

Authorizations:
BearerAuth
path Parameters
caseId
required
string <uuid>

The fraud case ID

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
content
required
string
noteType
string
Default: "review"
Enum: "review" "clarification" "decision"
actorId
required
string
actorName
string
actorType
string
Default: "user"
Enum: "user" "system" "workflow"

Responses

Response Schema: application/json
success
boolean
object (FraudCaseEvent)

Immutable event in fraud case audit log

Request samples

Content type
application/json
{
  • "content": "string",
  • "noteType": "review",
  • "actorId": "string",
  • "actorName": "string",
  • "actorType": "user"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "event": {
    }
}

Evaluate and optionally create case

Combined endpoint: Evaluate fraud signals AND create a case if warranted.

This is the recommended production workflow:

  1. Evaluate signals for an entity
  2. If signals trigger above threshold, automatically create a case
  3. Return both the alert and case for downstream processing

ADVISORY ONLY - does not block transactions or take automated actions.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
entityType
required
string (EvaluableEntityType)
Enum: "customer" "account" "agent" "merchant"
entityId
required
string
windowDays
integer [ 1 .. 365 ]
Default: 30
signalIds
Array of strings

Specific signals to run (optional - runs all applicable if omitted)

createCaseThreshold
number
Default: 30

Minimum score to trigger case creation

autoCreateCase
boolean
Default: true

Automatically create case if threshold exceeded

Responses

Response Schema: application/json
success
boolean
object (FraudAlert)

Advisory fraud alert - requires human review before any action. The isAdvisoryOnly field is always true to emphasize this is not a blocking decision.

object (FraudCase)

Immutable fraud case record for compliance review. Cases are append-only - changes are recorded via events.

caseCreated
boolean

True if a new case was created (false if already existed)

disclaimer
string

Request samples

Content type
application/json
{
  • "entityType": "customer",
  • "entityId": "string",
  • "windowDays": 30,
  • "signalIds": [
    ],
  • "createCaseThreshold": 30,
  • "autoCreateCase": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "alert": {
    },
  • "case": {
    },
  • "caseCreated": true,
  • "disclaimer": "string"
}

SME

SME business health intelligence. IMPORTANT: These endpoints produce advisory metrics only. They are NOT credit scores, NOT lending decisions, and should NOT be used as the sole basis for any financial decision. All metrics are derived from observable transaction patterns.

Calculate SME health metrics

Calculate business health indicators from transaction data. ADVISORY ONLY - not a credit score or lending decision.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
customerId
required
string <uuid>
windowDays
integer [ 7 .. 365 ]
Default: 90
includeCohort
boolean
Default: true
includeNarrative
boolean
Default: true

Responses

Response Schema: application/json
success
boolean
customerId
string
customerName
string
object
object (CohortPlacement)
object (SMEHealthNarrative)
evaluatedAt
string <date-time>
windowDays
integer
disclaimer
string

Reminder that this is advisory only, not a credit score

Request samples

Content type
application/json
{
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "windowDays": 90,
  • "includeCohort": true,
  • "includeNarrative": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "customerId": "string",
  • "customerName": "string",
  • "health": {
    },
  • "cohort": {
    },
  • "narrative": {
    },
  • "evaluatedAt": "2019-08-24T14:15:22Z",
  • "windowDays": 0,
  • "disclaimer": "string"
}

Get SME health for customer

Get business health indicators for a specific customer. ADVISORY ONLY - not a credit score or lending decision.

Authorizations:
BearerAuth
path Parameters
customerId
required
string <uuid>
query Parameters
windowDays
integer
Default: 90

Analysis window in days

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
customerId
string
customerName
string
object
object (CohortPlacement)
object (SMEHealthNarrative)
evaluatedAt
string <date-time>
windowDays
integer
disclaimer
string

Reminder that this is advisory only, not a credit score

Response samples

Content type
application/json
{
  • "success": true,
  • "customerId": "string",
  • "customerName": "string",
  • "health": {
    },
  • "cohort": {
    },
  • "narrative": {
    },
  • "evaluatedAt": "2019-08-24T14:15:22Z",
  • "windowDays": 0,
  • "disclaimer": "string"
}

List cohort benchmarks

List all available cohort benchmark definitions. Benchmarks are used to compare SME health metrics against peer groups.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
success
boolean
Array of objects (CohortBenchmark)
totalCount
integer
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "cohorts": [
    ],
  • "totalCount": 0,
  • "disclaimer": "string"
}

Agent Monitoring

Mobile money agent network monitoring and health intelligence. IMPORTANT: These endpoints produce DIAGNOSTIC indicators only. They are NOT predictions, NOT automatic suspension decisions, and NOT definitive risk scores. All flags are advisory and require human review before any action. Do not use as the sole basis for agent management decisions.

Get agent health index

Calculate Agent Health Index (AHI) for a mobile money agent. DIAGNOSTIC ONLY - not a prediction, automatic suspension decision, or risk score. All flags are advisory and require human review before action.

Authorizations:
BearerAuth
path Parameters
agentId
required
string

Mobile money agent ID

query Parameters
windowDays
integer [ 7 .. 90 ]
Default: 30

Analysis window in days

includePeerComparison
boolean
Default: true

Include peer benchmarking in response

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object (AgentHealthReport)

Complete agent health assessment (DIAGNOSTIC ONLY)

Response samples

Content type
application/json
{
  • "success": true,
  • "report": {
    }
}

Calculate agent health with provided data

Calculate Agent Health Index (AHI) with agent data provided in request body. Use this endpoint when you have agent metrics available directly. DIAGNOSTIC ONLY - not a prediction or automatic decision.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
agentId
required
string
agentCode
required
string
agentName
string
agentType
string
Default: "individual"
Enum: "individual" "corporate" "super_agent"
agentTier
required
string (AgentTier)
Enum: "basic" "standard" "premium" "super"

Agent tier classification

agentStatus
required
string (AgentStatus)
Enum: "active" "inactive" "suspended" "pending_verification"

Agent operational status

floatBalance
required
number >= 0
floatLimit
required
number >= 0
currency
string
Default: "GHS"
transactionCount30d
integer >= 0
transactionVolume30d
number >= 0
transactionCount7d
integer >= 0
transactionVolume7d
number >= 0
previousPeriodCount
integer >= 0
previousPeriodVolume
number >= 0
cashInCount30d
integer >= 0
cashOutCount30d
integer >= 0
cashInVolume30d
number >= 0
cashOutVolume30d
number >= 0
lastTransactionAt
string <date-time>
activatedAt
string <date-time>
createdAt
string <date-time>
region
string
servesRegions
Array of strings
includePeerComparison
boolean
Default: true

Responses

Response Schema: application/json
success
boolean
object (AgentHealthReport)

Complete agent health assessment (DIAGNOSTIC ONLY)

Request samples

Content type
application/json
{
  • "agentId": "string",
  • "agentCode": "string",
  • "agentName": "string",
  • "agentType": "individual",
  • "agentTier": "basic",
  • "agentStatus": "active",
  • "floatBalance": 0,
  • "floatLimit": 0,
  • "currency": "GHS",
  • "transactionCount30d": 0,
  • "transactionVolume30d": 0,
  • "transactionCount7d": 0,
  • "transactionVolume7d": 0,
  • "previousPeriodCount": 0,
  • "previousPeriodVolume": 0,
  • "cashInCount30d": 0,
  • "cashOutCount30d": 0,
  • "cashInVolume30d": 0,
  • "cashOutVolume30d": 0,
  • "lastTransactionAt": "2019-08-24T14:15:22Z",
  • "activatedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "region": "string",
  • "servesRegions": [
    ],
  • "includePeerComparison": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "report": {
    }
}

List agent benchmarks

List all available tier and regional benchmarks for agent comparison. These benchmarks represent typical performance across the agent network.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
success
boolean
object
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "benchmarks": {
    },
  • "disclaimer": "string"
}

Get portfolio-level agent health summary

Get aggregated health summary across the agent network. DIAGNOSTIC ONLY - requires human review before action on any flagged agents.

Authorizations:
BearerAuth
query Parameters
limit
integer <= 500
Default: 50
offset
integer
Default: 0
tier
string
Enum: "basic" "standard" "premium" "super"

Filter by agent tier

region
string

Filter by region

status
string
Enum: "active" "inactive" "suspended" "pending_verification"

Filter by agent status

minAHI
number [ 0 .. 100 ]

Minimum AHI score filter

maxAHI
number [ 0 .. 100 ]

Maximum AHI score filter

hasCriticalFlags
boolean

Filter to agents with critical flags

sortBy
string
Default: "ahiScore"
Enum: "ahiScore" "floatBalance" "transactionVolume" "agentCode"

Sort field

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

Sort order

header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (AgentHealthSummary)
total
integer
limit
integer
offset
integer
disclaimer
string

Reminder that all flags are diagnostic and require human review

Response samples

Content type
application/json
{
  • "success": true,
  • "agents": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "disclaimer": "string"
}

KYC-AML

KYC/AML workflow orchestration layer. IMPORTANT: This module provides WORKFLOW ORCHESTRATION only. It does NOT perform identity verification, document validation, or automated sanctions screening (unless lists are explicitly provided). It does NOT claim to automate KYC decision-making. All case outcomes require human review and determination. Regulatory report preparation is for internal use only and does NOT constitute official filing.

Evaluate AML trigger rules for an entity

Evaluate AML trigger rules against entity transaction history.

IMPORTANT DISCLAIMERS:

  • This produces ADVISORY signals only
  • It does NOT perform identity verification
  • It does NOT perform document validation
  • It does NOT perform sanctions screening (unless lists explicitly provided)
  • All outputs require human review before any action
Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Request Body schema: application/json
required
entityType
required
string
Enum: "customer" "account" "agent" "merchant" "counterparty"

Type of entity to evaluate

entityId
required
string

Entity identifier

windowDays
integer [ 7 .. 365 ]
Default: 30

Number of days for analysis window

ruleIds
Array of strings

Specific rule IDs to evaluate (default all enabled)

dryRun
boolean
Default: false

If true, evaluate without creating cases

highRiskCountries
Array of strings

List of high-risk country codes (required for geographic rules)

Responses

Response Schema: application/json
success
boolean
object (AmlEvaluationResult)
disclaimer
string

Mandatory compliance disclaimer

Request samples

Content type
application/json
{
  • "entityType": "customer",
  • "entityId": "string",
  • "windowDays": 30,
  • "ruleIds": [
    ],
  • "dryRun": false,
  • "highRiskCountries": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "result": {
    },
  • "disclaimer": "string"
}

List available AML trigger rules

List all available AML trigger rules and their configurations. Rules are deterministic and threshold-based - NOT ML models.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
Array of objects (AmlRule)
totalEnabled
integer
allRuleIds
Array of strings
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "rules": [
    ],
  • "totalEnabled": 0,
  • "allRuleIds": [
    ],
  • "disclaimer": "string"
}

Get default AML trigger thresholds

Get the default threshold values used by AML trigger rules. These can be customized per tenant via configuration.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object

Default threshold values for AML rules

disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "thresholds": {
    },
  • "disclaimer": "string"
}

Get valid case status transitions

Get the state machine for KYC/AML case status transitions. Cases follow a strict lifecycle from open to closed states.

Authorizations:
BearerAuth
header Parameters
x-tenant-id
required
string <uuid>

Tenant identifier

Responses

Response Schema: application/json
success
boolean
object

Map of status to valid target statuses

Array of objects
disclaimer
string

Response samples

Content type
application/json
{
  • "success": true,
  • "transitions": {
    },
  • "statusDetails": [
    ],
  • "disclaimer": "string"
}

We use cookies to ensure the website works properly and, with your consent, to analyse usage. Privacy Policy