Notifications

Send notification to recipient (synchronous)

200 does not always mean this recipient was reached. When no channel could carry the alert to them, the umbrella guarantee fires: the company owner is emailed that delivery failed, and THAT delivery is what the success body describes. It is reported in owner_fallback — see OwnerFallbackNotice. Check for that object before telling a human the alert arrived; without it the response is an ordinary delivery.

post/api/v1/notifications/send

Request

  • Base URL: https://wardenpoint.com (the document declares no server; this is the origin it was published from)
  • URL: https://wardenpoint.com/api/v1/notifications/send
  • Auth: API key in header X-API-Key

Request body

recipient_uuidstring uuid required

Who to wake up. The channel is NOT chosen here — it comes from that person's notification settings for the priority below.

Three failures worth telling apart, because they answer differently. A uuid that exists nowhere is a 422. A uuid belonging to another company passes the existence check and then fails to resolve inside your tenant, so it comes back as 404 — same as a typo would look, and not the 403 you might expect. And a recipient of yours who is deactivated is not refused at all: the send proceeds, and whether anything leaves depends on the routes their settings produce. Do not read a 2xx here as "this person is reachable"; read GET /recipients/{recipient}/availability for that.

messagestring required

The alert text, as the person will read it. On a voice channel it is also what gets spoken: the text is synthesised to speech and cached, so the same wording costs the synthesiser only once. Keep it self-contained — a human woken at 4am sees this and nothing else.

priority'low' | 'normal' | 'high' | 'critical'

Which of the recipient's four notification settings applies — that is what actually picks the channel, the escalation ladder, and whether quiet hours are bypassed. Not a label: critical and low can route to entirely different providers. Defaults to normal when omitted.

audio_filestring nullable

Path to a ready-made audio file in this installation's storage, for voice channels. An API client normally has no such path and should omit this: the voice is then synthesised from message. A path that does not resolve is not an error — it is logged and the text is synthesised instead, so a typo here costs a delay, not a lost alert.

max_attemptsinteger

How many delivery attempts one channel may make before the step is considered failed. Defaults to 3 when omitted. This is retrying the SAME channel, not escalation: handing the alert to the next person is the escalation ladder's job and is configured on the recipient, not here.

Response

Notification sent — or, when owner_fallback is present, the alert reached nobody and the account owner was emailed instead. Successful responses carry a delivery object describing where this company stands against its plan quota — see DeliveryOverageState. Exceeding that quota never blocks a send; only the non-tariff daily ceiling does, and that answers 429 with code: DELIVERY_CEILING_REACHED.

Changes

No recorded changes to this operation across all 1 revision of this API.