Get last observations

Retrieve recent FHIR Observation resources with the Ovok last-observations operation.

Returns one patient's newest FHIR Observation resources, up to max per code, newest first. Name the observation codes or categories to read.

MethodPath
GET/fhir/R4/Observation/$lastn

The unversioned and R5 aliases are /fhir/Observation/$lastn and /fhir/R5/Observation/$lastn.

Access requirements

Send a valid bearer token. The operation reads the Patient and its Observations as the caller, so the caller's AccessPolicy must allow both.

A Patient caller may leave out patient and subject to read its own Observations. Every other caller must name the patient with patient or subject, or the request fails with 400 INVALID_LASTN.

Set withAlerts=true to include Signals alerts. This also needs the custom signals_alerts:read capability and Signals read access to the Patient. See Signals route policies.

Request

Name at least one code or category. Send either patient or subject, not two different patients.

ParameterTypeRequiredDescription
patientstringNon-patient callersThe patient: Patient/:patient-id or :patient-id.
subjectstringNoSame as patient.
codestringWithout categoryObservation codes, comma separated or repeated. Each is system|code or code, for example http://loinc.org|8886-4. At most 50 codes.
categorystringWithout codeObservation categories, comma separated or repeated.
maxstringNoHow many Observations to return per code, a whole number from 1 to 1000. Defaults to 1.
withAlertsstringNotrue includes the Signals alerts on the returned Observations. false is the default.

Any other search parameter, such as date, is applied to each search as given. _count, _sort, _offset and _project are ignored.

With code, each code is searched on its own, so max=2 and two codes return up to four Observations. With only category, Ovok reads the category's newest 1,000 Observations and keeps up to max per code.

curl --get 'https://api.sandbox.ovok.com/fhir/R4/Observation/$lastn' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode "patient=Patient/${PATIENT_ID}" \
  --data-urlencode 'max=2' \
  --data-urlencode 'code=131328,8886-4'

--get places the supplied values in the URL query string. Set OVOK_TOKEN to an access token authorized for the requested patient data. This example returns up to two Observations for each of the two codes.

Successful response

The operation returns a FHIR Bundle with type: searchset. Each entry contains an Observation and its canonical fullUrl. Per code, Observations are ordered newest clinical time first. total counts the matching Observations only.

Response pathExampleMeaning
resourceTypeBundleIdentifies the outer FHIR resource.
typesearchsetIndicates the Bundle contains search results.
entry[].fullUrlhttps://api.sandbox.ovok.com/fhir/R4/Observation/<observation-id>Canonical URL identifying the returned Observation.
entry[].resource.resourceTypeObservationEach entry contains an Observation resource.
entry[].resource.id<observation-id>ID of the returned Observation.
entry[].resource.statusfinalClinical status of the observation.
entry[].resource.subject.referencePatient/<patient-id>Patient associated with the observation.
entry[].resource.code.coding[0]http://loinc.org / 8886-4Code system and code identifying what was measured.
entry[].resource.valueQuantity72 bpmExample measurement and unit. Other value types may be used.

The returned fields depend on the stored Observation. Each entry's resource contains one matching Observation.

Include alerts

With withAlerts=true, Ovok reads the Signals alerts on the returned Observations. It appends them after the Observations, as entries with search.mode set to include:

Response pathExampleMeaning
entry[].fullUrlurn:uuid:<alert-id>The Signals alert id. The alert is not stored in Ovok, so it has no id.
entry[].resource.resourceTypeDetectedIssueOne Signals alert.
entry[].resource.implicated[0].referenceObservation/<observation-id>The Observation the alert is on.
entry[].search.modeincludeMarks the entry as included, not a match.

Alerts never fail the request. If they are incomplete, the Bundle carries an OperationOutcome entry with search.mode set to outcome and a warning issue:

issue[].codeMeaning
transientSignals alerts could not be read. The Observations are complete without them.
too-costlyOnly some of the alerts are included. Name fewer codes or a lower max.

A request with only category can return a too-costly warning too: only the category's newest 1,000 Observations were read. Name codes to reach older ones.

Responses and errors

Errors are Problem Details (application/problem+json). The type ends in the error code, for example /errors/invalid-lastn.

HTTP statusMeaning
200Request succeeded; the body is a searchset Bundle.
400INVALID_LASTN: no code or category, more than 50 codes, two different patients, no patient for a non-patient caller, max outside 1-1000, or withAlerts not true or false. SEARCH_REFUSED: the FHIR store rejected a search, for example a bad passed-through parameter.
401The access token is missing or invalid.
403With withAlerts=true, the caller lacks signals_alerts:read or Signals access to the Patient. The FHIR store can also refuse a read as SEARCH_REFUSED with its own client status.
404The Patient does not exist or is not visible to the caller (SEARCH_REFUSED).
502The FHIR store failed.
503The FHIR store is overloaded or unavailable. Retry later.
504The FHIR store timed out.

Last updated on

On this page