Create night report PDF
Create night report PDF using Ovok’s Slim API.
| Method | Path |
|---|---|
POST | /v1/slim/export/pdf |
Authentication · Access policies
Creates a night report PDF for one resident and stores it. Optionally emails the PDF. Use it for the report download and email feature on the dashboard.
Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and needs search and read on Patient, Device and Observation.
Scope: the caller's project (from the token). The resident is read with your token, so Ovok AccessPolicy limits which residents you can export.
Request
Body
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Report type. Must be TRENDS_PDF_EXPORT. |
patientId | string (uuid) | Yes | The resident to report on. |
language | string | Yes | Language of the report and the email, as a locale code such as en or de. A short code is mapped to its regional code, for example en to en-US. |
period | object | Yes | Report period. |
period.start | string (ISO 8601 date-time) | Yes | Start of the period. |
period.end | string (ISO 8601 date-time) | Yes | End of the period. |
mailTo | string[] | No | Email addresses to send the PDF to. Each must be a valid address and is lowercased. Default []. |
timeZone | string | No | Ignored. The project's time zone is used. |
Behaviour
codemust beTRENDS_PDF_EXPORT. Any other value is rejected with400.- The report layout comes from the export template content for
codeandlanguage. A template in your project wins over one in its parent project. The route returns400when no template exists. - The report period is
(period.start, period.end]in the project's time zone: for a range of more than one day the first day is left out, because its night belongs to the day before. A single-day range reports that day. A night counts for the day its sleep ends. - The report covers sleep statistics, heart rate and respiratory rate for each night. It holds only what ends inside one of the resident's use periods of its device, as
GET /v1/slim/sleep/statisticsdoes: the sleep table's recordings, and the readings behind the heart and respiratory rate rows and charts. A reading with no end time is then left out. So a previous resident's night that ended before the device was handed over, but reached Ovok after it, is not reported. A resident with no device use history has everything reported. - When a night has several sleep recordings left, the sleep table uses the one written last (latest
meta.lastUpdated), the ruleGET /v1/slim/sleep/statisticsuses. - Once a resident has any use period, the report also leaves out what a device with no period of theirs recorded, and what a device recorded before its earliest period. A device assigned before use periods were recorded gets its first one on its next edit in Ovok, starting at the Device's last write before that edit, so what it recorded before then is not reported.
- Report times use the project's time zone. The
timeZonefield in the body is not used. - The PDF is stored as a Binary, and a
DocumentReferencelinks it to the resident. Both are written in one transaction, so a failed store leaves neither. The response is thatDocumentReference. Itscontent[0].attachment.urlpoints to the Binary. - When
mailTohas addresses, the PDF is emailed to them as an attachment after the store succeeds. The email is sent in the language you set. With no addresses, nothing is emailed. - If the email cannot be sent, the route returns
500, but the report has already been stored. - Every call creates a new report. Nothing is deduplicated.
Example
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/export/pdf' \
-H "Authorization: Bearer ${OVOK_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"code": "TRENDS_PDF_EXPORT",
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
"language": "en",
"period": { "start": "2026-09-21T00:00:00Z", "end": "2026-09-28T00:00:00Z" },
"mailTo": ["team@example.com"]
}'Successful response
201 — The stored DocumentReference that links the PDF to the resident.
The body is the stored FHIR DocumentReference that links the PDF to the resident. It is returned as the FHIR server stored it, so it can carry more fields than shown. Trimmed example:
{
"resourceType": "DocumentReference",
"id": "9d3b5f71-8a2c-4e06-b4d9-1c7e3a5f9b82",
"meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68" },
"status": "current",
"date": "2026-10-09T08:15:00.000Z",
"category": [
{
"coding": [
{ "system": "https://api.ovok.com/fhir/StructureDefinition/document-type", "code": "export" }
]
}
],
"subject": { "reference": "Patient/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21", "display": "demo-resident" },
"author": [{ "reference": "Practitioner/d2c8f4a0-6b3e-4175-9e2d-8a1c5f7b3e46", "display": "Alex Example" }],
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "https://api.sandbox.ovok.com/fhir/R4/Binary/c5e7a9b1-3d2f-4a68-9b0c-4e6f8a1d3b57",
"title": "demo-resident.pdf"
}
}
]
}| Field | Type | Description |
|---|---|---|
resourceType | "DocumentReference" | Always DocumentReference. |
id | string (uuid) | DocumentReference id. |
meta.project | string (uuid) | Project the report is stored in. |
status | "current" | Always current. |
date | string (ISO 8601 date-time) | When the report was created. |
category | object[] | One entry. Its coding has system https://api.ovok.com/fhir/StructureDefinition/document-type and code export. |
subject.reference | string | Patient/ followed by the patient id. |
subject.display | string | The resident's name. Left out when the resident has no name. |
author | object[] | The caller who created the report. Left out when the session has no profile. |
author[].reference | string | Reference to the caller's profile, such as Practitioner/<id>. |
author[].display | string | The caller's name. Unknown when the profile has none. |
content | object[] | One entry with the PDF. |
content[].attachment.contentType | "application/pdf" | Always application/pdf. |
content[].attachment.url | string | URL of the Binary that holds the PDF. |
content[].attachment.title | string | PDF file name. Derived from the resident's name, or resident.pdf when it has none. |
Errors
| Status | Meaning |
|---|---|
400 | Your session has no project, the resident cannot be read, code is not TRENDS_PDF_EXPORT, no export template exists for code and language (or it has no main content), or the period covers no night. |
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, or you lack search or read on Patient, Device or Observation. |
422 | The body fails validation. |
500 | The PDF was stored but the email to mailTo could not be sent, or the charts took longer than 60 seconds to render. |
502 | A FHIR read failed while collecting observations, devices or the resident's device use periods, or the PDF could not be stored. |
Last updated on