Benefit Calculation Service - API Contract

GET /api/v1/benefit-calculations/api/v1/benefit-calculations

List all benefit calculations

Public

Response Example

{
  "data": [
    {
      "id": "calc_7f3a2b1c",
      "hours_saved": 12.5,
      "travel_cost_avoided": 87.5,
      "health_system_offset": 375,
      "input": {
        "mentor_id": "mentor_001",
        "organisation_id": "org_42",
        "sessions": 25,
        "avg_minutes": 30,
        "cost_per_session": 3.5,
        "cost_per_hour": 30
      },
      "created_at": "2026-03-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/benefit-calculations/api/v1/benefit-calculations/:id

Get a specific benefit calculation by ID

Public

Response Example

{
  "id": "calc_7f3a2b1c",
  "hours_saved": 12.5,
  "travel_cost_avoided": 87.5,
  "health_system_offset": 375,
  "input": {
    "mentor_id": "mentor_001",
    "organisation_id": "org_42",
    "sessions": 25,
    "avg_minutes": 30,
    "cost_per_session": 3.5,
    "cost_per_hour": 30
  },
  "created_at": "2026-03-20T14:30:00Z"
}

POST /api/v1/benefit-calculations/api/v1/benefit-calculations

Trigger a new benefit calculation for a mentor

Public

Request Example

{
  "mentor_id": "mentor_001",
  "organisation_id": "org_42",
  "sessions": 25,
  "avg_minutes": 30,
  "cost_per_session": 3.5,
  "cost_per_hour": 30
}

Response Example

{
  "id": "calc_9d1e4f2a",
  "hours_saved": 12.5,
  "travel_cost_avoided": 87.5,
  "health_system_offset": 375,
  "input": {
    "mentor_id": "mentor_001",
    "organisation_id": "org_42",
    "sessions": 25,
    "avg_minutes": 30,
    "cost_per_session": 3.5,
    "cost_per_hour": 30
  },
  "created_at": "2026-03-26T09:15:00Z"
}

PUT /api/v1/benefit-calculations/api/v1/benefit-calculations/:id

Update a benefit calculation's input parameters and recalculate

Public

Request Example

{
  "sessions": 30,
  "avg_minutes": 35,
  "cost_per_session": 4,
  "cost_per_hour": 32
}

Response Example

{
  "id": "calc_7f3a2b1c",
  "hours_saved": 17.5,
  "travel_cost_avoided": 120,
  "health_system_offset": 560,
  "input": {
    "mentor_id": "mentor_001",
    "organisation_id": "org_42",
    "sessions": 30,
    "avg_minutes": 35,
    "cost_per_session": 4,
    "cost_per_hour": 32
  },
  "created_at": "2026-03-20T14:30:00Z",
  "updated_at": "2026-03-26T10:00:00Z"
}

DELETE /api/v1/benefit-calculations/api/v1/benefit-calculations/:id

Delete a benefit calculation record

Public

Response Example

{
  "deleted": true,
  "id": "calc_7f3a2b1c"
}

POST /api/v1/benefit-calculations/api/v1/benefit-calculations/hours-saved

Calculate hours saved from session count and average duration

Public

Request Example

{
  "sessions": 25,
  "avg_minutes": 30
}

Response Example

{
  "hours_saved": 12.5
}

POST /api/v1/benefit-calculations/api/v1/benefit-calculations/travel-cost-avoided

Calculate total travel cost avoided across sessions

Public

Request Example

{
  "sessions": 25,
  "cost_per_session": 3.5
}

Response Example

{
  "travel_cost_avoided": 87.5
}

POST /api/v1/benefit-calculations/api/v1/benefit-calculations/health-system-offset

Calculate health system cost offset based on hours saved

Public

Request Example

{
  "hours_saved": 12.5,
  "cost_per_hour": 30
}

Response Example

{
  "health_system_offset": 375
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}