Create a patient

Create a Signals patient with the Manager app and set the heart-rate band that decides when a reading alerts.

Complexity
1/5
Clients
Any HTTP client
Time
5 minutes

Signals judges readings per patient, so create one before you post a reading. You do it with the Manager app from Get started.

.env
OVOK_MANAGER_ID=…
OVOK_MANAGER_SECRET=…

Set a band and turn on episodesTerminal

A new tenant has no heart-rate band, so nothing alerts yet. Set one for every patient, and turn on episodes so related breaches are grouped into one event.

curl --request PATCH 'https://api.sandbox.ovok.com/v1/signals/api/tenant' \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{"orgSettings":{"bands":{"8867-4":{"low":40,"high":110}}},"settings":{"episodicAlerts":true}}'

Create the patientTerminal

Name the patient with your own id, refId. Creating the same refId again updates it.

curl --request POST 'https://api.sandbox.ovok.com/v1/signals/api/patient' \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{"patients":[{"refId":"resident-001","name":"Resident 001"}]}'

The answer lists the patients as stored. The full contract is Create patients.

Try it hereClient-side

Pick the sandbox server, choose Basic authentication, and enter your Manager id and secret. Send the request to create resident-001.

POST
/v1/signals/api/patient

Upserts on refId: posting a patient that already exists updates it rather than duplicating it, so a replayed provisioning run is safe. Each entry's config — flags and triggers — is applied in the same call, and metadata is merged.

Through ovok

  • Capabilities: signals_patients:update, held by Manager apps. See app types.
  • ovok adds your project's submitter to each new patient and stamps metadata.project with your project. Sending config also needs signals_config:update and signals_silence:update. New patients count toward your plan's monitored-patient cap.
  • Patient access: every patient the body names must be one you can update. See patient access.

Authorization

headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
patients*array<>

Response Body

The patients as stored, in request order.

application/json
  1. response
[index: integer]?
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/api/patient' \  -H 'Content-Type: application/json' \  -d '{  "patients": [    {      "refId": "resident-001",      "name": "Resident 001"    },    {      "refId": "resident-002",      "name": "Resident 002"    }  ]}'
Example Response
[  {    "_id": "00000000-0000-4000-8000-000000000002",    "id": "00000000-0000-4000-8000-000000000002",    "tenantId": "00000000-0000-4000-8000-000000000001",    "refId": "resident-001",    "name": "Resident 001",    "submitters": [      "ovok-submitter-00000000-0000-4000-8000-000000000001"    ],    "subscribers": [],    "alertIfEmpty": true,    "alertIfNote": false,    "alertInactiveDays": 2,    "alertsPaused": false,    "metadata": {      "room": "101",      "project": "00000000-0000-4000-8000-000000000003"    },    "configUpdatedAt": "2026-01-09T14:53:00.184Z",    "lastSeenAt": "2026-01-09T14:47:57.726Z",    "createdAt": "2026-01-09T14:52:58.487Z",    "updatedAt": "2026-01-09T14:56:06.444Z",    "manager": "ovok-manager-00000000-0000-4000-8000-000000000001",    "tenant": "00000000-0000-4000-8000-000000000001",    "config": {      "alertIfEmpty": true,      "alertIfNote": false,      "alertInactiveDays": 2,      "updatedAt": "2026-01-09T14:53:00.184Z",      "triggers": {        "8867-4": {          "code": "8867-4",          "system": null,          "display": null,          "valueKey": "value",          "constants": {            "low": 45,            "high": 100          },          "logic": null,          "metadata": {},          "version": 1,          "updatedAt": "2026-01-09T14:53:00.184Z"        }      }    }  },  {    "_id": "00000000-0000-4000-8000-000000000004",    "id": "00000000-0000-4000-8000-000000000004",    "tenantId": "00000000-0000-4000-8000-000000000001",    "refId": "resident-002",    "name": "Resident 002",    "submitters": [      "ovok-submitter-00000000-0000-4000-8000-000000000001"    ],    "subscribers": [],    "alertIfEmpty": false,    "alertIfNote": false,    "alertInactiveDays": null,    "alertsPaused": false,    "metadata": {      "project": "00000000-0000-4000-8000-000000000003"    },    "configUpdatedAt": null,    "lastSeenAt": null,    "createdAt": "2026-01-09T14:56:06.448Z",    "updatedAt": "2026-01-09T14:56:06.452Z",    "manager": "ovok-manager-00000000-0000-4000-8000-000000000001",    "tenant": "00000000-0000-4000-8000-000000000001",    "config": {      "alertIfEmpty": false,      "alertIfNote": false,      "alertInactiveDays": null,      "updatedAt": null,      "triggers": {}    }  }]

Verify your integration

The answer is 200 and holds resident-001. If it isn't:

  1. 401: the id or secret is wrong, or is not a Manager app.
  2. 403: the app lacks signals_patients:update. See app types.

Next

Send a reading posts a heart rate above the band.

Last updated on

On this page