Indicators API

Indicator Definitions

List indicators

GET /orgs/:orgId/indicators

Optional query params:

• ?resultNodeId=uuid — filter by result node
• ?projectId=uuid — only indicators linked to a project

Response

[
  {
    "id": "uuid",
    "name": "# of people with access to clean water",
    "code": "WASH-01",
    "unit": "people",
    "aggregationMethod": "sum",
    "resultNodeId": "uuid",
    "isFormula": false,
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

---

Create indicator

POST /orgs/:orgId/indicators

Body

{
  "name": "# of people with access to clean water",
  "code": "WASH-01",
  "unit": "people",
  "aggregationMethod": "sum",
  "description": "Cumulative count of individuals who gained access to improved water sources.",
  "dataSource": "Beneficiary registration + household survey",
  "resultNodeId": "uuid"
}

Aggregation methods: sum | average | latest | min | max

---

Create formula indicator

POST /orgs/:orgId/indicators

{
  "name": "% households with safe water access",
  "code": "WASH-PCT-01",
  "unit": "%",
  "aggregationMethod": "latest",
  "isFormula": true,
  "formula": "WASH-01 / WASH-TOTAL * 100"
}

Formula syntax uses indicator code values as variables. Evaluated at report generation time.

---

Update indicator

PATCH /orgs/:orgId/indicators/:id

Body — any subset of indicator fields.

---

Delete indicator

DELETE /orgs/:orgId/indicators/:id

Cannot delete if there are existing IndicatorReport records.

---

Linking Indicators to Projects

Link indicator

POST /orgs/:orgId/projects/:projectId/indicators

{
  "indicatorId": "uuid",
  "target": 5000,
  "baseline": 0,
  "baselineYear": 2024
}

---

Unlink indicator

DELETE /orgs/:orgId/projects/:projectId/indicators/:indicatorId

---

Indicator Reports (Values)

List reports for a project

GET /orgs/:orgId/projects/:projectId/indicator-reports

Query params:

• ?periodId=uuid — filter by reporting period
• ?status=approved — filter by status (draft, submitted, approved, rejected)
• ?indicatorId=uuid — filter by indicator

---

Submit a value

POST /orgs/:orgId/projects/:projectId/indicator-reports

{
  "indicatorId": "uuid",
  "reportingPeriodId": "uuid",
  "value": 4250,
  "target": 5000,
  "narrative": "Training sessions completed in 5 sectors. Some delays due to rains.",
  "disaggregatedValues": {
    "Female": 2100,
    "Male": 2150
  }
}

---

Update a report

PATCH /orgs/:orgId/indicator-reports/:id

Can only update if status is draft or rejected.

---

Approve a report

PATCH /orgs/:orgId/indicator-reports/:id/approve

Required role: me_officer or org_admin

{ "comment": "Values verified against field registers." }

---

Reject a report

PATCH /orgs/:orgId/indicator-reports/:id/reject

{ "comment": "Value appears inflated — please verify with field data." }

Reporter is notified and can edit and resubmit.

---

Disaggregations

Add disaggregation to indicator

POST /orgs/:orgId/indicators/:id/disaggregations

{
  "name": "Sex",
  "categories": ["Female", "Male", "Non-binary"]
}

List disaggregations

GET /orgs/:orgId/indicators/:id/disaggregations