> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/api-reference/enterprise-modules.md).

# Enterprise Modules

All enterprise endpoints require a valid JWT token via the header:

```
Authorization: Bearer <access_token>
```

The token is obtained via `POST /api/v1/auth/login`. See [Authentication](/api-reference/authentication.md).

***

## Module 1 — AI Campaign Optimizer

**Base URL** : `/api/v1/ai`

### `GET /ai/insights`

Full AI analysis report for the current program.

**200 response:**

```json
{
  "health": {
    "score": 94.4,
    "level": "HIGH",
    "components": {
      "job_success": 86.1,
      "quota_health": 100.0,
      "balance_health": 99.9
    }
  },
  "card_forecast": {
    "predictions": [
      { "date": "2026-05-17", "value": 51.98 },
      { "date": "2026-05-18", "value": 54.58 }
    ],
    "confidence": 0.82,
    "r_squared": 0.82,
    "slope": 2.6
  },
  "spend_forecast": { "...": "same structure" },
  "quota_saturation": {
    "will_saturate": false,
    "days_until_saturation": null,
    "saturation_pct": 12.3
  },
  "card_anomalies": [
    { "index": 14, "value": 312.0, "zscore": 2.8 }
  ],
  "spend_anomalies": [],
  "recommendations": [
    {
      "category": "quota",
      "priority": "high",
      "title": "Monthly quota at 75%",
      "body": "Usage: 78% of the monthly quota...",
      "action_url": "billing"
    }
  ],
  "metrics": {
    "quota_pct": 12.3,
    "cards_used_month": 370,
    "quota_total": 3000,
    "job_success_rate": 86.1,
    "balance_fcfa": 1248500,
    "days_until_reset": 14
  }
}
```

***

### `GET /ai/health-score`

Composite health score only (without time series).

**200 response:**

```json
{
  "score": 94.4,
  "level": "HIGH",
  "components": {
    "job_success": 86.1,
    "quota_health": 100.0,
    "balance_health": 99.9
  }
}
```

***

### `GET /ai/forecast`

30-day OLS forecast for cards and spending.

**200 response:**

```json
{
  "card_forecast": {
    "predictions": [ { "date": "YYYY-MM-DD", "value": 0.0 } ],
    "confidence": 0.0,
    "r_squared": 0.0,
    "slope": 0.0
  },
  "spend_forecast": { "...": "same structure in FCFA" }
}
```

> If the history contains fewer than 3 points: `{ "predictions": [], "confidence": 0.0, "r_squared": 0.0, "slope": 0.0 }`

***

### `GET /ai/recommendations`

List of active contextual recommendations.

**200 response:**

```json
{
  "recommendations": [
    {
      "category": "quota | budget | risk | dhis2 | distribution",
      "priority": "critical | high | medium | low",
      "title": "string",
      "body": "string",
      "action_url": "billing | monitor | dhis2 | null"
    }
  ],
  "count": 1
}
```

***

### `GET /ai/anomalies`

Outliers detected by Z-score (threshold 2.2σ) over the last 90 days.

**200 response:**

```json
{
  "card_anomalies": [
    { "index": 14, "value": 312.0, "zscore": 2.83 }
  ],
  "spend_anomalies": [],
  "total_anomalies": 1
}
```

***

## Module 2 — Geospatial Command Center

**Base URL** : `/api/v1/geo`

### `GET /geo/overview`

Geographical overview of the current program.

**200 response:**

```json
{
  "programme_id": "uuid",
  "country": "Senegal",
  "period": "2026-05",
  "total_campaigns": 90,
  "total_jobs": 72,
  "total_cards": 325,
  "success_rate": 86.1,
  "active_regions": 3,
  "coverage_score": 3
}
```

***

### `GET /geo/regions`

Stats by region derived from campaign prefixes.

**200 response:**

```json
{
  "regions": [
    {
      "region": "Dakar",
      "country": "Senegal",
      "period": "2026-05",
      "campaigns_count": 12,
      "cards_generated": 108,
      "beneficiaries_count": 91,
      "coverage_pct": 33.2,
      "distribution_success_rate": 86.1,
      "risk_score": 35.0
    }
  ],
  "count": 3
}
```

***

### `GET /geo/heatmap`

Normalized heatmap matrix for a given metric.

**Parameters:**

| Parameter | Type   | Values                                                                                              | Default           |
| --------- | ------ | --------------------------------------------------------------------------------------------------- | ----------------- |
| `metric`  | string | `cards_generated`, `coverage_pct`, `risk_score`, `distribution_success_rate`, `beneficiaries_count` | `cards_generated` |

**200 response:**

```json
{
  "cells": [
    {
      "region": "Dakar",
      "value": 108.0,
      "intensity": 1.0,
      "color": "#08BCF1"
    },
    {
      "region": "Thiès",
      "value": 54.0,
      "intensity": 0.5,
      "color": "#08BCF180"
    }
  ],
  "max_value": 108.0,
  "metric": "cards_generated",
  "label": "Cards generated"
}
```

***

### `GET /geo/risk-zones`

Regions whose risk score exceeds 30 or whose coverage is below 40%.

**200 response:**

```json
{
  "zones": [
    {
      "region": "Kédougou",
      "risk_score": 65.0,
      "risk_level": "HIGH",
      "coverage_pct": 12.5,
      "distribution_success_rate": 86.1,
      "cards_generated": 36
    }
  ],
  "count": 1
}
```

***

### `GET /geo/live-events`

Real-time distribution event stream.

**Parameters:**

| Parameter | Type    | Default |
| --------- | ------- | ------- |
| `limit`   | integer | 20      |

**200 response:**

```json
{
  "events": [
    {
      "id": "uuid",
      "region": "Dakar",
      "channel": "whatsapp | sms | qr",
      "event_type": "sent | delivered | failed",
      "count": 3,
      "created_at": "2026-05-17T10:23:00Z"
    }
  ],
  "count": 12
}
```

***

### `GET /geo/admin/overview` *(Admin)*

Cross-program aggregated overview (admins only).

**200 response:**

```json
{
  "total_programmes": 5,
  "total_cards": 8420,
  "total_regions": 12,
  "global_success_rate": 84.2,
  "programmes": [ { "...": "..." } ]
}
```

***

## Module 3 — Health Trust Score

**Base URL** : `/api/v1/mpi/trust`

### `GET /mpi/trust/me`

Trust Score for the current user (based on `programme.id`).

**200 response:**

```json
{
  "mpi_id": "SN-DKR-26-9XQ7LM2A",
  "score": 72.5,
  "level": "MEDIUM",
  "computed_at": "2026-05-17T08:00:00Z",
  "components": {
    "kyc_verified": true,
    "has_nin": false,
    "programmes_count": 2
  }
}
```

***

### `GET /mpi/trust/{mpi_id}`

Trust Score for a specific MPI ID.

**Parameters:**

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `mpi_id`  | string | MPI identifier (e.g. `SN-DKR-26-9XQ7LM2A`) |

**200 response:** Same structure as `/mpi/trust/me`.

***

### `POST /mpi/trust/{mpi_id}/compute`

Recompute the Trust Score on demand.

**200 response:**

```json
{
  "mpi_id": "SN-DKR-26-9XQ7LM2A",
  "score": 85.0,
  "level": "HIGH",
  "computed_at": "2026-05-17T10:30:00Z"
}
```

***

### `GET /mpi/trust/{mpi_id}/history`

Trust Score history.

**200 response:**

```json
{
  "history": [
    { "score": 55.0, "level": "LOW", "computed_at": "2026-04-01T..." },
    { "score": 72.5, "level": "MEDIUM", "computed_at": "2026-05-01T..." }
  ],
  "count": 2
}
```

***

### `GET /mpi/trust/{mpi_id}/risks`

Active risk signals for an MPI ID.

**200 response:**

```json
{
  "risks": [
    {
      "risk_type": "probable_duplicate | demographic_inconsistency | missing_nin",
      "severity": "HIGH | MEDIUM | LOW",
      "description": "A probable duplicate (score 82/100) was identified.",
      "detected_at": "2026-05-10T..."
    }
  ],
  "count": 1
}
```

***

### `POST /mpi/trust/admin/recompute` *(Admin)*

Batch recomputation of all Trust Scores.

**200 response:**

```json
{
  "recomputed": 142,
  "duration_ms": 3420
}
```

***

## Module 4 — Sovereign Wallet

**Base URL** : `/api/v1/wallet`

### `POST /wallet/pass`

Create or retrieve a pass (idempotent on `mpi_id`).

**Body:**

```json
{
  "mpi_id": "SN-DKR-26-9XQ7LM2A",
  "holder_name": "Fatou Diallo",
  "holder_id": "1234567890123",
  "campaign_id": "uuid",
  "campaign_name": "CPS Dakar 2026",
  "pass_type": "health | vaccination | distribution",
  "expires_at": "2027-05-17T00:00:00Z"
}
```

**200/201 response:**

```json
{
  "id": "uuid",
  "pass_id": "8A06586D268B79A3",
  "mpi_id": "SN-DKR-26-9XQ7LM2A",
  "holder_name": "Fatou Diallo",
  "pass_type": "health",
  "status": "active",
  "qr_payload": "SN-DKR-26-9XQ7LM2A:8A06586D268B79A3:health",
  "qr_signature": "hmac-sha256-hex",
  "issued_at": "2026-05-17T10:00:00Z",
  "expires_at": "2027-05-17T00:00:00Z",
  "created_at": "2026-05-17T10:00:00Z"
}
```

***

### `GET /wallet/pass/{mpi_id}`

Active pass for a beneficiary by MPI ID.

**200 response:** Same structure as `POST /wallet/pass`. **404 response:** No active pass for this MPI ID.

***

### `GET /wallet/passes`

Paginated list of program passes.

**Parameters:**

| Parameter | Type    | Values                         | Default |
| --------- | ------- | ------------------------------ | ------- |
| `status`  | string  | `active`, `revoked`, `expired` | all     |
| `limit`   | integer | 1–500                          | 100     |
| `offset`  | integer | ≥ 0                            | 0       |

**200 response:**

```json
{
  "passes": [ { "...": "..." } ],
  "total": 42,
  "stats": {
    "total": 42,
    "active": 38,
    "revoked": 3,
    "expired": 1,
    "devices_registered": 12
  }
}
```

***

### `POST /wallet/pass/{pass_id}/revoke`

Revoke a pass with a reason.

**Body:**

```json
{
  "reason": "Deceased beneficiary | Duplicate identified | Data error"
}
```

**200 response:**

```json
{
  "pass_id": "8A06586D268B79A3",
  "status": "revoked",
  "revoked_at": "2026-05-17T11:00:00Z",
  "reason": "Duplicate identified"
}
```

***

### `GET /wallet/pass/{pass_id}/bundle`

Encrypted offline bundle for IndexedDB storage.

**200 response:**

```json
{
  "pass_id": "8A06586D268B79A3",
  "bundle": {
    "algo": "xor-sha256",
    "encrypted": "<base64>",
    "hash": "<sha256-hex>",
    "expires_at": "2027-05-17T00:00:00Z"
  }
}
```

***

### `POST /wallet/device/register`

Register a device for synchronization.

**Body:**

```json
{
  "device_token": "unique-device-identifier",
  "device_name": "Field Tablet 01",
  "platform": "android | ios | web"
}
```

**201 response:**

```json
{
  "device_id": "uuid",
  "device_token": "unique-device-identifier",
  "registered_at": "2026-05-17T..."
}
```

***

### `GET /wallet/devices`

Program's registered devices.

**200 response:**

```json
{
  "devices": [
    {
      "id": "uuid",
      "device_token": "...",
      "device_name": "Field Tablet 01",
      "platform": "android",
      "last_sync": "2026-05-16T..."
    }
  ],
  "count": 3
}
```

***

### `GET /wallet/sync`

Passes to synchronize for a given device.

**Parameters:**

| Parameter      | Type   | Required |
| -------------- | ------ | -------- |
| `device_token` | string | Yes      |

**200 response:**

```json
{
  "passes": [ { "...": "..." } ],
  "sync_token": "uuid",
  "synced_at": "2026-05-17T..."
}
```

***

### `GET /wallet/sync/history`

Program synchronization history.

**200 response:**

```json
{
  "history": [
    {
      "sync_token": "uuid",
      "device_token": "...",
      "passes_synced": 38,
      "synced_at": "2026-05-16T..."
    }
  ],
  "count": 12
}
```

***

### `GET /wallet/stats`

Program wallet statistics.

**200 response:**

```json
{
  "total": 42,
  "active": 38,
  "revoked": 3,
  "expired": 1,
  "devices_registered": 12
}
```

***

## Module 5 — Advanced Analytics

**Base URL** : `/api/v1/analytics`

### `GET /analytics/summary`

Key metrics over the last N days (Studio + DHIS2 combined). Available without premium module.

**Query params** : `days` (int, default 30)

**200 response:**

```json
{
  "period_days": 30,
  "total_campaigns": 12,
  "all_campaigns": 48,
  "total_jobs": 34,
  "total_cards": 2850,
  "completed_jobs": 31,
  "failed_jobs": 1,
  "success_rate": 91.2,
  "total_spend_fcfa": 142500,
  "balance_fcfa": 857500,
  "cards_total": 12400
}
```

> `cards_total` = total all-time (Studio + DHIS2) since `EngineUsageRecord`. Shows `0` if no real card was generated — no seeded value.

***

### `GET /analytics/studio-stats`

All-time Studio + DHIS2 statistics from the database (persistent source of truth).

**200 response:**

```json
{
  "total_cards": 8200,
  "dhis2_cards": 4150,
  "jobs_by_status": { "completed": 42, "failed": 2, "running": 1 },
  "cards_by_status": { "completed": 8200 },
  "dpi_distribution": [
    { "render_scale": 1.0, "jobs": 38, "cards": 7400 },
    { "render_scale": 1.4, "jobs": 4,  "cards": 800 }
  ],
  "sms_sent": 1240,
  "whatsapp_sent": 380,
  "qr_verified": 622,
  "storage_mb": 1840,
  "pdf_exports": 18,
  "cost_fcfa": 41000,
  "total_cost_fcfa": 54200
}
```

> `total_cards` : Studio cards (`GenerationJob` status=completed). `dhis2_cards` : DHIS2 cards from `EngineUsageRecord` engine\_mode=`studio_print` — **v5.12**, persistent DB source with no TTL limit.

***

### `GET /analytics/campaigns-timeline`

Daily Studio + DHIS2 trend over N days.

**Query params** : `days` (int, default 30)

**200 response:**

```json
[
  {
    "date": "2026-05-20",
    "jobs": 3,
    "cards": 450,
    "dhis2_cards": 200
  }
]
```

> `dhis2_cards` : DHIS2 cards for the day from `EngineUsageRecord.last_updated`. `cards` = total (Studio + DHIS2).

***

### `GET /analytics/spend-timeline`

Spend trend over N days.

**Query params** : `days` (int, default 30)

**200 response:**

```json
[{ "date": "2026-05-20", "amount_fcfa": 4750 }]
```

***

## Common error codes

| Code  | Meaning                                                             |
| ----- | ------------------------------------------------------------------- |
| `401` | Token missing, invalid, or expired                                  |
| `403` | Insufficient permission (e.g. Admin endpoint)                       |
| `404` | Resource not found (unknown MPI ID, pass\_id)                       |
| `422` | Missing required parameter (e.g. `device_token` for `/wallet/sync`) |
| `500` | Internal error — check the API logs                                 |

***

## See also

* [Authentication](/api-reference/authentication.md)
* [Campaigns & Jobs](/api-reference/campaigns-and-jobs.md)
* [Billing](/api-reference/billing.md)
* [MPI](/api-reference/mpi.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/api-reference/enterprise-modules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.