Benefit Share Service - API Contract

GET /api/v1/benefit-shares/api/v1/benefit-shares

List all share events for benefit calculation results

Public

Response Example

{
  "data": [
    {
      "id": "share_a3c8e1f2",
      "calculation_id": "calc_7f3a2b1c",
      "mentor_id": "mentor_001",
      "share_text": "I've saved 12.5 hours and avoided €87.50 in travel costs through 25 peer mentoring sessions!",
      "shared_at": "2026-03-22T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

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

Get a specific share event by ID

Public

Response Example

{
  "id": "share_a3c8e1f2",
  "calculation_id": "calc_7f3a2b1c",
  "mentor_id": "mentor_001",
  "share_text": "I've saved 12.5 hours and avoided €87.50 in travel costs through 25 peer mentoring sessions!",
  "shared_at": "2026-03-22T11:00:00Z"
}

POST /api/v1/benefit-shares/api/v1/benefit-shares

Create a share event for a benefit calculation result

Public

Request Example

{
  "calculation_id": "calc_7f3a2b1c",
  "mentor_id": "mentor_001"
}

Response Example

{
  "id": "share_b5d9f3a1",
  "calculation_id": "calc_7f3a2b1c",
  "mentor_id": "mentor_001",
  "share_text": "I've saved 12.5 hours and avoided €87.50 in travel costs through 25 peer mentoring sessions!",
  "shared_at": "2026-03-26T09:30:00Z"
}

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

Update a share event record (e.g. mark as delivered)

Public

Request Example

{
  "delivery_status": "delivered",
  "delivery_channel": "native_share"
}

Response Example

{
  "id": "share_a3c8e1f2",
  "calculation_id": "calc_7f3a2b1c",
  "mentor_id": "mentor_001",
  "share_text": "I've saved 12.5 hours and avoided €87.50 in travel costs through 25 peer mentoring sessions!",
  "delivery_status": "delivered",
  "delivery_channel": "native_share",
  "shared_at": "2026-03-22T11:00:00Z"
}

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

Delete a share event record

Public

Response Example

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

POST /api/v1/benefit-shares/api/v1/benefit-shares/preview-text

Generate share text for a benefit calculation result without recording a share event

Public

Request Example

{
  "calculation_id": "calc_7f3a2b1c"
}

Response Example

{
  "share_text": "I've saved 12.5 hours and avoided €87.50 in travel costs through 25 peer mentoring sessions!"
}

Additional Metadata

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