Send Notification

POST 
/notifications-srv/notifications

Sends a template-based notification to one or more recipients through a supported communication channel: email, SMS, IVR, push, or chat.

How It Works

The API selects an appropriate template based on the criteria provided, then renders it using the attributes supplied in the request. The rendered message is dispatched via the specified communication method.

Note: If the matched template is disabled or marked as draft, the notification is silently skipped — no message is sent and the recipient's eventStatus will reflect skipped. Ensure the template is active and published before triggering a notification.

---

Template Selection (criteria)

The criteria controls which template is selected and how it is delivered:

Field	Required	Description
commMethod	Yes	Delivery channel: email, sms, ivr, push, chat
groupId	Yes	Communication group whose settings (sender, provider, etc.) are used
locale	Yes	Preferred locale for the template (e.g. de-DE). Falls back to the tenant default if no match is found
defaultLocale	No	Fallback locale if the requested locale is unavailable (e.g. de-DE)
processingType	No	LINK, CODE, or GENERAL — determines how the notification payload is processed
templateKey	Yes	The action key that identifies the template (e.g. VERIFY_USER)
usageType	No	Context of use: MULTIFACTOR_AUTHENTICATION, PASSWORDLESS_AUTHENTICATION, VERIFICATION_CONFIGURATION
verificationType	No	Verification method: TOUCHID, VOICE, FACE, PUSH, EMAIL, SMS, IVR, PATTERN
number	No	Reminder sequence number (1–5), used for opt-in reminder flows

---

Recipients (recipientAddresses)

Each recipient entry specifies the delivery address and the attributes used to render the template for that individual.

• Single recipient requests must contain exactly 1 entry in recipientAddresses.
• Multiple recipient requests support up to 100 entries per request.

{
  "address": "+4915123456789",
  "name": "Klaus Müller",
  "systemAttributes": {},
  "customAttributes": {},
  "contextAttributes": {}
}

• address — The delivery target (phone number, email address, device token, etc.)
• name — Display name of the recipient
• Per-recipient attributes (see Attribute Types below) are specific to that individual, such as given_name, family_name, email, mobile_number, or date_of_birth

---

Root-Level Attributes (for multiple recipients)

When sending to multiple recipients, you can define attributes at the root of the request body. These are shared across all recipients and should contain values that are common to all, such as:

• systemAttributes — e.g. account_name: "Meine GmbH", org_country: "DE"
• customAttributes — e.g. newsletter_opt_in: true
• contextAttributes — e.g. client_id, creationTime

Important: Root-level attributes are merged with per-recipient attributes during template rendering. If the same key exists at both levels, the per-recipient value always takes precedence. Use root-level attributes only for values that are truly identical across all recipients.

---

Attribute Types

Three attribute categories are available at both the recipient level and the root level:

Type	Contents
systemAttributes	Standard profile fields: given_name (e.g. Klaus), family_name (e.g. Müller), email, mobile_number (e.g. +4915123456789), sub, code, account_name (e.g. Meine GmbH), etc.
customAttributes	App defined custom fields for the user (e.g. steuer_id, newsletter_opt_in)
contextAttributes	Request/session context: client_id, device_id, sub, creationTime

---

Sender Overrides

If senderName, senderAddress, or replyAddress are omitted, the API falls back to the communication group settings (groupId) or the communication provider configuration.

---

Message Format (content)

• data — Channel-specific payload. For most channels this is null. For push notifications, populate this object (all fields optional):

Push Notification Data (content.data)

Field	Type	Description
data	map[string]string	Arbitrary key-value pairs delivered silently to the app alongside the notification. The app can read these values and act on them without displaying them to the user (e.g. routing to a specific screen).
topic	string	A topic name that allows a single notification to be fanned out to all devices subscribed to that topic, instead of targeting individual device tokens.
image_url	string	URL of an image to display inside the notification (supported on Android and iOS with rich notifications enabled).
priority	string	Delivery priority. high wakes the device immediately and is suited for time-sensitive alerts (e.g. OTP, incoming call). normal defers delivery until the device is active, conserving battery. Defaults to normal.
click_action	string	The Android intent or iOS deep-link URL to invoke when the user taps the notification. Typically used to open a specific screen in the app.
analytics_label	string	A label attached to the notification event for Firebase Analytics reporting. Use this to segment and compare notification performance across different campaigns or flows.
validate_only	boolean	When true, the message is sent to Firebase for structural validation but is not delivered to any device. Useful for testing payload correctness without triggering real notifications.

Example push content.data:

{
  "data": {
    "screen": "verify",
    "action": "otp"
  },
  "topic": "auth-alerts",
  "image_url": "https://cdn.example.com/logo.png",
  "priority": "high",
  "click_action": "OPEN_VERIFICATION_SCREEN",
  "analytics_label": "passwordless-sms",
  "validate_only": false
}

All other channels (email, SMS, IVR, chat) — Set data to null or omit the field entirely.

---

Attachments

File attachments can be included by sending the request as multipart/form-data. Two fields are supported:

Field	Description
attachment	A single file to attach to the notification (e.g. a PDF invoice or a Rechnung).
attachments	Multiple files to attach in one request. Use when the notification needs to carry more than one document (e.g. Vertrag + AGB).

Content-Type: When sending attachments, the request must use Content-Type: multipart/form-data. Requests that include attachment or attachments cannot use application/json. All other body fields (e.g. criteria, recipientAddresses) must be included as form parts in the same multipart request.

Attachments are supported for email notifications only.

Request

Responses

200

OK — Notification dispatched. Check data[].status for per-recipient delivery outcome.

400

Bad Request — returned when request validation fails or the resolved template has an empty subject or body.

401

Unauthorized

Response Headers

header-0

404

Not Found