Deliver Notification¶

Sends a push notification to one patient or provider in your organisation, and adds it to their in-app notification list.

Endpoint¶

POST /v2/notifications/deliver

Headers¶

Header	Required	Description
`Idempotency-Key`	No	Recommended. A retry with the same key is accepted again without sending the notification twice.

Request Body¶

Parameter	Type	Required	Description
`recipient`	object	Yes	Who to notify: exactly one of `patient_id` or `provider_id`. See Recipient.
`notification`	object	Yes	What to send. See Notification.

Recipient¶

Parameter	Type	Required	Description
`patient_id`	string	Conditional	The patient to notify. Delivered to the app account that owns the patient record — the patient's own, or a parent's for a dependant. Send this or `provider_id`, not both.
`provider_id`	string	Conditional	The provider to notify. Send this or `patient_id`, not both.

Notification¶

Parameter	Type	Required	Description
`title`	string	Yes	Push title. Also the title of the in-app entry.
`body`	string	No	Push body text.
`link`	string	No	Deep link the notification opens when tapped.

Request¶

To a patient:

curl --location '{base_url}/v2/notifications/deliver' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "recipient": {
    "patient_id": "63120"
  },
  "notification": {
    "title": "Your appointment is tomorrow",
    "body": "See you at 10:00 AM.",
    "link": "type=appointment&appointment_id=418907"
  }
}'

To a provider:

curl --location '{base_url}/v2/notifications/deliver' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "recipient": {
    "provider_id": "2094"
  },
  "notification": {
    "title": "New message",
    "body": "You have a new message."
  }
}'

Response¶

Success Response¶

Code: 202 Accepted

{
  "notification_id": "ntf_6f1c2a9e-1b7d-4a53-9a51-0f3c8f2e4d10",
  "status": "accepted"
}

Response Fields¶

Field	Type	Description
`notification_id`	string	Identifier for this notification, in the form `ntf_<uuid>`.
`status`	string	Always `accepted`: the notification is queued, not yet delivered.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

202 means the notification was accepted and queued, not that it reached a device. Delivery happens in the background, and a failed send doesn't change the response you already got.
Push is the only channel. A recipient with no registered device gets the in-app entry only.
Address the recipient by patient_id or provider_id — exactly one. They must belong to your organisation, and for a token limited to specific clinics, to one of those clinics; anyone else returns 404. A patient with no app account returns 400.
A patient's notification goes to the app account that owns their record, which for a dependant is the parent's.
Patient app tokens can't send notifications and get 403.
The organisation comes from your access token. An organisation_id or org_id in the body is rejected with 400.
title and link can be up to 500 characters and body up to 1000; longer is a 400.
Send an Idempotency-Key (up to 255 characters) to make retries safe: a retry with the same key answers 202 again, with a new notification_id, and isn't sent a second time. Without a key, every request is a new notification.
There is no read endpoint for a notification yet, so notification_id is for your own correlation and support requests.