API Guide

How to send requests to the FHIR Goals Engine and which codes to use for Goals and Observations.

FHIR R4 (v4.0.1) references

Resource and data-type definitions from the official HL7 FHIR specification:

• Patient — hl7.org/fhir/R4/patient.html
• Goal — hl7.org/fhir/R4/goal.html
• Observation — hl7.org/fhir/R4/observation.html
• Bundle — hl7.org/fhir/R4/bundle.html
• OperationOutcome — hl7.org/fhir/R4/operationoutcome.html
• Data types (Reference, CodeableConcept, Quantity, etc.) — hl7.org/fhir/R4/datatypes.html

Base URL & Headers

Use your server origin (e.g. http://localhost:8080 or your deployed URL). All API requests should use:

• Content-Type: application/fhir+json
• Accept: application/fhir+json (optional; JSON is the default)

Search and read responses return FHIR Bundle or single resources. Errors return OperationOutcome.

Endpoints Overview

Resource	Endpoints	Search params
Patient	GET/POST /Patient, GET/PUT/DELETE /Patient/{id}	name, gender
Goal	GET/POST /Goal, GET/PUT/DELETE /Goal/{id}	patient, status, category
Observation	GET/POST /Observation, GET/PUT/DELETE /Observation/{id}	patient, code, date
Metadata	GET /metadata	—

Goals — Codes & Structure

Goal lifecycle status

Use one of these for lifecycleStatus. Only goals with status active are evaluated when new observations are created.

Status	Meaning
proposed	Proposed
planned	Planned
accepted	Accepted
active	Active (evaluated by engine)
on-hold	On hold
completed	Completed
cancelled	Cancelled
entered-in-error	Entered in error
rejected	Rejected

Goal achievement status

Optional. Set when updating a goal (e.g. achieved when the target is met). The engine sets this automatically when an observation meets the target.

Code	Meaning
in-progress	In progress
improving	Improving
worsening	Worsening
no-change	No change
achieved	Achieved
sustaining	Sustaining
not-achieved	Not achieved
no-progress	No progress
not-attainable	Not attainable

LOINC codes for goal targets (auto-achievement)

Goal targets use measure.coding[].code from LOINC. Only the codes below trigger automatic goal achievement when you create an observation with the same code.

LOINC code	Display	Direction	Goal achieved when
29463-7	Body weight	Decrease	Observation value ≤ target
8480-6	Systolic BP	Decrease	Observation value ≤ target
4548-4	HbA1c	Decrease	Observation value ≤ target
41950-7	Steps per day	Increase	Observation value ≥ target

Example: Create a Goal

POST /Goal
Content-Type: application/fhir+json

{
  "resourceType": "Goal",
  "lifecycleStatus": "active",
  "description": { "text": "Reduce body weight to 80 kg" },
  "subject": { "reference": "Patient/YOUR-PATIENT-ID" },
  "category": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/goal-category",
      "code": "dietary",
      "display": "Dietary"
    }]
  }],
  "target": [{
    "measure": {
      "coding": [{ "system": "http://loinc.org", "code": "29463-7", "display": "Body Weight" }]
    },
    "detailQuantity": { "value": 80, "unit": "kg", "system": "http://unitsofmeasure.org" },
    "dueDate": "2026-06-01"
  }],
  "startDate": "2026-03-01"
}

Observations — Codes & Structure

Observation status

Required. Use one of:

Status
registered
preliminary
final
amended
corrected
cancelled
entered-in-error
unknown

Observation code (LOINC)

Required. code.coding[0].code must be set. Use the same LOINC codes as in goal targets if you want the engine to evaluate goals (see table above).

Observation category

Optional. category classifies the type of observation (e.g. vital signs vs lab). It does not affect goal evaluation; use it for display or filtering.

• system — The code system. For FHIR observation categories use http://terminology.hl7.org/CodeSystem/observation-category.
• code — A code from that system, e.g. vital-signs, laboratory, activity, social-history, imaging, procedure, exam, or survey.
• display — Human-readable label (e.g. "Vital Signs", "Laboratory").

Common pairings: weight/BP → vital-signs; HbA1c → laboratory; steps → activity. You can omit category if you don’t need it.

Examples: Create an Observation (triggers goal evaluation)

Use the same LOINC code and unit as the goal target. For decrease goals (weight, BP, HbA1c), value must be ≤ target. For increase goals (steps), value must be ≥ target.

Body weight (goal “reduce to 80 kg”):

POST /Observation
Content-Type: application/fhir+json

{
  "resourceType": "Observation",
  "status": "final",
  "code": {
    "coding": [{ "system": "http://loinc.org", "code": "29463-7", "display": "Body Weight" }]
  },
  "subject": { "reference": "Patient/YOUR-PATIENT-ID" },
  "effectiveDateTime": "2026-03-06T12:00:00Z",
  "valueQuantity": {
    "value": 79,
    "unit": "kg",
    "system": "http://unitsofmeasure.org",
    "code": "kg"
  },
  "category": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/observation-category",
      "code": "vital-signs",
      "display": "Vital Signs"
    }]
  }]
}

If the patient has an active goal with target measure 29463-7 and target value 80, this observation (79 kg) will mark that goal as achieved.

HbA1c (goal “reduce below 6.5%”):

POST /Observation
Content-Type: application/fhir+json

{
  "resourceType": "Observation",
  "status": "final",
  "code": {
    "coding": [{ "system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c" }]
  },
  "subject": { "reference": "Patient/YOUR-PATIENT-ID" },
  "effectiveDateTime": "2026-03-06T14:00:00Z",
  "valueQuantity": {
    "value": 6.4,
    "unit": "%",
    "system": "http://unitsofmeasure.org",
    "code": "%"
  },
  "category": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/observation-category",
      "code": "laboratory",
      "display": "Laboratory"
    }]
  }]
}

Value must be ≤ 6.5 to achieve a “below 6.5%” goal. A goal.achieved WebSocket event is broadcast when the goal is marked achieved.

Patients — Minimal Create

POST /Patient
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "active": true,
  "name": [{ "family": "Smith", "given": ["Jane"] }],
  "gender": "female",
  "birthDate": "1985-05-20"
}

Postman collection

Download Postman collection — Import this JSON into Postman to get ready-made requests for Patient, Goal, and Observation CRUD. Use your server URL as the baseUrl variable.

Testing from the dashboard

Open the Terminal from the header, then use the Raw tab or the API collections sidebar to send requests. Replace example-patient-id, example-goal-id, and example-observation-id with IDs from your selected patient (the UI substitutes these when you pick a request from the sidebar).