# Create night report PDF

Canonical page: https://docs.ovok.com/slim-apis/export/create-night-report-pdf

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/export/pdf` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Body [#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 [#behaviour]

- `code` must be `TRENDS_PDF_EXPORT`. Any other value is rejected with `400`.
- The report layout comes from the export template content for `code` and `language`. A template in your project wins over one in its parent project. The route returns `400` when 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/statistics` does: 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 rule `GET /v1/slim/sleep/statistics` uses.
- 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 `timeZone` field in the body is not used.
- The PDF is stored as a Binary, and a `DocumentReference` links it to the resident. Both are written in one transaction, so a failed store leaves neither. The response is that `DocumentReference`. Its `content[0].attachment.url` points to the Binary.
- When `mailTo` has 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 [#example]

```bash
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 [#successful-response]

`201` — The stored DocumentReference that links the PDF to the resident.

The body is the stored FHIR [`DocumentReference`](/api/fhir/r4/document-reference) 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:

```json
{
  "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 [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | 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`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, or you lack `search` or `read` on Patient, Device or Observation. |
| [`422`](/errors/validation-failed) | The body fails validation. |
| [`500`](/errors/internal-error) | The PDF was stored but the email to `mailTo` could not be sent, or the charts took longer than 60 seconds to render. |
| [`502`](/errors/upstream-error) | A FHIR read failed while collecting observations, devices or the resident's device use periods, or the PDF could not be stored. |
