List a patient's readings
List a patient's readings, through Ovok's Signals gateway.
List a patient's readings
| Method | Path |
|---|---|
GET | /v1/signals/api/observation/{patientId} |
- Sandbox: available
- Staging: available
- Production: unknown
Newest first by clinical time, in v1's envelope {items, total, page, pageSize, totalPages} with nest's nextCursor. from, to and code (comma-separated) filter as in v1; category (comma-separated) keeps the readings carrying any of those FHIR category codes. With from, a reading whose clinical time is more than an hour ahead of when it was stored is not found: the read skips the storage older than that, so it never waits on it. pageSize defaults to 10; above 200 it needs both from and to, and then reaches 10000. A page may start at most 10000 rows in; walk further with cursor.
Each item is a flat timeline entry (code, valueNumber, observedAt, category, valueSampledData, components, effectiveStart, effectiveEnd, deviceId, …) with v1's _id, id, patient, valueQuantity and createdAt beside it. fields=code,valueNumber returns exactly those keys instead.
Through ovok
- Who can call it: Manager apps, and users whose access policy grants the capabilities.
- Capabilities, all required:
signals_observations:read. Project admins have every capability; client applications get no admin bypass. - If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can read. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a
refId; ovok asks Signals which patient a Signals id is.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
patientId | string | Yes | The Signals patient id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | 1-based, as v1 paged. A page may start at most 10000 rows in; walk further with cursor. |
pageSize | number | No | v1's page size; defaults to 10. Wins over limit when both are sent. |
from | string | No | Inclusive lower bound on clinical time; a reading timed over an hour after it was stored is missed. |
to | string | No | Inclusive upper bound on the reading's clinical time. |
code | string | No | One LOINC code, or several separated by commas. |
category | string | No | One FHIR category code, or several separated by commas; a reading carrying any of them. |
limit | number | No | — |
cursor | string | No | — |
fields | string | No | Only these keys of each item, separated by commas (code,valueNumber,observedAt). Every key when absent. A chart reading a day of readings needs a few of them. |
Responses
| Status | Meaning |
|---|---|
200 | One page of readings. |
400 | A path value holds a character ovok does not send to Signals, such as a raw : or +. Percent-encode it. The query carries a raw #, or more than 200 parameters. |
401 | Your ovok access token, or your client id and secret, are missing or invalid. |
403 | ovok refused the call: you lack a capability this route needs, or your session has no project. From Signals: Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | A patient the call names is not one you can read. From Signals: No such patient in this tenant. |
409 | Your project has no Signals tenant of its own (SIGNALS_TENANT_NOT_OWN), or it is moving to another one. |
422 | A patient id is not 1 to 64 letters, digits, ., _, ~ or -. From Signals: A query parameter failed validation, a large page lacked from/to, or the page starts too deep. |
429 | Too many requests. Retry after the seconds in Retry-After. |
500 | ovok hit an unexpected fault, such as your project having no Signals submitter. |
502 | Signals answered with something ovok couldn't use, or refused ovok's own credential. |
503 | Signals is unavailable. Retry after the seconds in Retry-After. |
504 | Signals did not answer in time. |
Example
curl --request GET 'https://api.sandbox.ovok.com/v1/signals/api/observation/:patientId' \
--user "${OVOK_CLIENT_ID}:${OVOK_CLIENT_SECRET}"Last updated on