Deliver Notification

Sends a push notification to a single recipient. Validation is synchronous; delivery is not.

Endpoint

POST /apis/v1/notifications/deliver

Request Body

Parameter	Type	Required	Description
recipient	object	Yes	Who to notify (see Recipient)
notification	object	Yes	What to send (see Notification)
idempotency_key	string	No	Dedup key. Two requests carrying the same key produce one notification; without a key, a retry sends again

Recipient

Parameter	Type	Required	Description
user_id	string	Yes	Spry user ID of the person to notify. Devices are resolved from this ID
user_type	string	Yes	PATIENT or PROVIDER. Case-insensitive; any other value returns 400 Bad Request

Notification

Parameter	Type	Required	Description
title	string	Yes	Push title. Also the title of the in-app entry
body	string	No	Push body
link	string	No	Deep link the notification opens, e.g. type=conversation&conversation_id=abc123

Request

curl --location '{base_url}/apis/v1/notifications/deliver' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "recipient": {
      "user_id": "usr_123",
      "user_type": "PROVIDER"
    },
    "notification": {
      "title": "New message",
      "body": "You have a new message.",
      "link": "type=conversation&conversation_id=abc123"
    },
    "idempotency_key": "msg_987"
  }'

Response

Success Response

Code: 202 Accepted

{
  "notification_id": "ntf_9f1c2e5a-1b2c-4d3e-8f9a-0a1b2c3d4e5f",
  "status": "accepted"
}

Response Fields

Field	Type	Description
notification_id	string	Identifier for this notification, in the form ntf_<uuid>
status	string	Always accepted

Error Response

Code: 400 Bad Request

Returned for malformed JSON, a missing recipient.user_id or notification.title, or a user_type outside the allowed values.

{
  "error": "bad_request",
  "message": "recipient.user_type must be PATIENT or PROVIDER"
}

Code: 401 Unauthorized

{
  "error": "unauthorized",
  "message": "authorization header required"
}