Claim valuation timeline

Heyrafiki records when each Claim fact became effective and when the system learned it. This bitemporal history separates service, report, adjudication, remittance and settlement lag, and makes an as-of financial view reproducible.

Business time

effective_at records when the underlying Care, decision or money fact took effect.

Knowledge time

recorded_at records when Heyrafiki received and persisted the fact.

Valuation time

valuation_at excludes every fact recorded after the stated cutoff.

A backdated adjustment first received on 2 August does not change what was known on 31 July. Re-run the same cutoff and the same ordered event history produces the same result.

One Claim, three clocks

The public fixture keeps policy reference and version, source authority, reason codes and bounded evidence references with every relevant transition. Person identity and clinical content remain outside the payer timeline.

Reproduce the as-of amount

For the synthetic fixture, all money is in integer KES minor units:

billed = payer_liability + patient_responsibility + adjustment
600000 = 450000 + 50000 + 100000

outstanding = payer_liability - observed_settlement
100000 = 450000 - 350000

Remittance remains payer advice. Settlement remains independent evidence of money movement. The timeline does not mark a Claim settled from an advice file alone.

Actuarial
Finance
Oversight
Engineering

Reconstruct reported Claim development by service, report, decision and settlement dates. Preserve zero-Claim exposure and define the cohort, valuation basis and treatment of reopened or reversed Claims before calculating a portfolio measure.

Call the valuation

Use the Claim identifier created by the Sandbox flow and supply an explicit ISO 8601 cutoff. The operation requires claims:read and returns only facts whose business time and knowledge time are both on or before the cutoff.

curl --get "https://api.heyrafiki.space/v1/claims/$CLAIM_ID/valuation" \
  --header "Authorization: Bearer $HEYRAFIKI_API_KEY" \
  --data-urlencode "valuation_at=2026-07-31T23:59:59.000Z"

import { Heyrafiki } from "@heyrafiki/rafiki-js";

const heyrafiki = new Heyrafiki({
  apiKey: process.env.HEYRAFIKI_API_KEY,
});

const valuation = await heyrafiki.claims.valuation(
  process.env.CLAIM_ID,
  { valuationAt: "2026-07-31T23:59:59.000Z" },
);

console.log(valuation.amount.outstanding);

import os
import requests

response = requests.get(
    f"https://api.heyrafiki.space/v1/claims/{os.environ['CLAIM_ID']}/valuation",
    headers={"Authorization": f"Bearer {os.environ['HEYRAFIKI_API_KEY']}"},
    params={"valuation_at": "2026-07-31T23:59:59.000Z"},
    timeout=10,
)
response.raise_for_status()
print(response.json()["amount"]["outstanding"])

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
    "time"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    endpoint := "https://api.heyrafiki.space/v1/claims/" +
        url.PathEscape(os.Getenv("CLAIM_ID")) + "/valuation"
    request, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        panic(err)
    }
    query := request.URL.Query()
    query.Set("valuation_at", "2026-07-31T23:59:59.000Z")
    request.URL.RawQuery = query.Encode()
    request.Header.Set("Authorization", "Bearer "+os.Getenv("HEYRAFIKI_API_KEY"))

    response, err := http.DefaultClient.Do(request)
    if err != nil {
        panic(err)
    }
    defer response.Body.Close()
    if response.StatusCode != http.StatusOK {
        panic(fmt.Sprintf("valuation failed: %s", response.Status))
    }

    var valuation struct {
        Amount struct {
            Outstanding int64 `json:"outstanding"`
        } `json:"amount"`
    }
    if err := json.NewDecoder(response.Body).Decode(&valuation); err != nil {
        panic(err)
    }
    fmt.Println(valuation.Amount.Outstanding)
}

200 · Claim valuation

{
  "id": "clm_synthetic_001:2026-07-31T23:59:59.000Z",
  "object": "claim_valuation",
  "claim_id": "clm_synthetic_001",
  "valuation_at": "2026-07-31T23:59:59.000Z",
  "currency": "KES",
  "status": "partially_approved",
  "amount": {
    "billed": 600000,
    "payer_liability": 450000,
    "patient_responsibility": 50000,
    "adjustment": 100000,
    "remitted": 350000,
    "settled": 350000,
    "outstanding": 100000
  },
  "policy": {
    "reference": "policy:mental-health:001",
    "version": "2026-01"
  },
  "events": [
    {
      "sequence": 2,
      "type": "partially_approved",
      "effective_at": "2026-07-14T10:00:00.000Z",
      "recorded_at": "2026-07-14T10:00:01.000Z",
      "previous_status": "submitted",
      "next_status": "partially_approved",
      "reason_code": "covered_with_cost_share",
      "evidence_references": ["policy:mental-health:001:2026-01"]
    }
  ]
}

The response includes the ordered Claim events with effective_at, recorded_at, status transitions, reason codes and bounded evidence references. The GET /claims/{claim_id}/valuation API reference contains the complete schema and error format.

Inspect the public evidence

The valuation fixture, JSON Schema and conformance test live in Proving Ground.

git clone https://github.com/heyrafiki/proving-ground.git
cd proving-ground
npm ci
npm run test:financial-controls

The check rejects future knowledge, invalid sequence, non-integer money, unbalanced adjudication and an outstanding amount that cannot be reproduced.

Actuarial boundary

This timeline supports analysis of reported Claims and reproducible outstanding observations. Portfolio reserve selection, IBNR, premium liability, capital, solvency, reinsurance and actuarial opinions remain with the insurer and its appointed actuarial authority.

The open fixture uses synthetic data. An approved Organization can test the same workflow in the Sandbox, then define its production data mapping, valuation policy and control owners through the institutional review.

Continue with financial controls, the Assurance Graph and the acceptance test plan.

Payer workflows

Integration assurance

Claim valuation timeline

Business time

Knowledge time

Valuation time

One Claim, three clocks

Reproduce the as-of amount

Call the valuation

Inspect the public evidence

Actuarial boundary

Business time

Knowledge time

Valuation time

​One Claim, three clocks

​Reproduce the as-of amount

​Call the valuation

​Inspect the public evidence

​Actuarial boundary

One Claim, three clocks

Reproduce the as-of amount

Call the valuation

Inspect the public evidence

Actuarial boundary