Send notifications
Endpoint for sending a notification through a chosen notification channel to one or more recipient.
Endpoint
POST /orders
Authentication
This API requires authentication and the request must also include one of the following:
- Maskinporten scope altinn:serviceowner/notifications.create (for external system callers)
- Platform Access Token (for Altinn Apps and internal Altinn systems)
See Authentication and Authorization for more information.
Request
Content-type
application/json
Request body
The request body must contain the order request formatted as an NotificationOrderRequestExt and serialized as JSON.
Required order request properties
notificationChannel
Type: enum NotificationChannelExt
The notification channel to use when sending the notification.
recipients
Type: List of RecipientExt
A list containing one or more recipient objects, each recipient containing either an email address, a national identity number or an organization number.
Optional order request properties
emailTemplate
Type: EmailTemplateExt
The template property for the email notifications.
smsTemplate
Type: SmsTemplateExt
The template property for the SMS notifications.
requestedSendTime
Type: DateTime
Default: Current time
The date and time (with time zone specification) when the notification should be sent to recipient.
sendersReference
Type: string
An internal reference for notification creator to lookup or identify the notification in the future. Could be a case number or another id. It is recommended, but not required, that the sender’s reference is unique within the organization’s notification orders.
resourceId
Type: string
The ID of the Altinn resource the notifications should be related to as the ID appears in the Altinn Resource Registry.
For an Altinn app with ID {org}/{app} the format of the resourceId is app_{org}_{app} e.g. app_ttd_apps-test.
ignoreReservation
Type: boolan
A boolean indicating wether the notification content satisfies the requirements for overriding KRR reservations when sending notifications to an individual.
conditionEndpoint
Type: Url
The URL to use when checking whether the condition to send the notification is met.
Response
Response codes
- 202 Accepted: The request was accepted and a notification order has been successfully generated.
- 400 Bad Request: The request was invalid. Refer to problem details in response body for further information.
- 401 Unauthorized: Indicates a missing, invalid or expired authorization header.
- 403 Forbidden: Indicates missing or invalid scope or Platform Access Token.
Content-Type
- application/json
Response body
The response body is formatted as an NotificationOrderRequestResponseExt.cs and serialized as JSON.
Find a short description of each property below.
orderId
Type: GUID
The generated ID for the notification order.
recipientLookup*
Type: RecipientLookupResultExt
The result object describing the result of the recipient lookup containing the properties below.
- status: the result of the initial lookup
- isReserved: a list containing national identity numbers for recipients that are reserved
- missingContact: a list containing national identity numbers and organization numbers for recipients where contact details for selected notification channel were not identified
| Status | Description |
|---|---|
| Success | The recipient lookup was successful for all recipients. |
| PartialSuccess | The recipient lookup was successful for some recipients. |
| Failed | The recipient lookup failed for all recipients. |
* Property is only included if order request requires recipient lookup
Response headers
Location
Type: URL
The self link for the generated notification order
Examples
Request
In the example we have included place holders for both the Platform Access and Altinn token.
You only need one of them, reference the Authentication section for which one applies to your use case.
curl --location 'https://platform.altinn.no/notifications/api/v1/orders/email' \
--header 'Content-Type: application/json' \
--header 'PlatformAccessToken: [INSERT PLATFORM ACCESS TOKEN]' \
--header 'Authorization: Bearer [INSERT ALTINN TOKEN]' \
--data-raw '{
"emailTemplate": {
"subject": "Demo email subject",
"body": "Demo email body",
"content-type": "Plain"
},
"smsTemplate": {
"body": "Demo SMS content"
},
"notificationChannel": "emailPreferred",
"recipients": [
{
"emailAddress": "stephanie.buadu@avanade.com"
}
],
"resourceId": "app_ttd_apps-test"
}'
Response
202 Accepted
In cases where reservation check or address lookup of recipients is required for an order, the initial result of the lookup will be included in the response. This includes a list containing national identity number for all reserved persons and a list containing national identity number or organization number for the recipients we could not find contact details for.
Headers:
-- header 'Location: https://platform.altinn.no/notifications/api/v1/orders/f1a1cc30-197f-4f34-8304-006ce4945fd1'
Body:
{
"orderId": "f1a1cc30-197f-4f34-8304-006ce4945fd1",
"recipientLookup": {
"status": "PartialSuccess",
"isReserved": ["11876995923"],
"missingContact": []
}
}
400 Bad Request
Response contains a problem details object with the error message in the detail property.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"NotificationChannel": [
"A notification channel must be defined."
]
},
"traceId": "00-24d7cbf2a13f938741e8d2351d535556-2c30279c4891e50f-00"
}