Last modified: Aug 8, 2024

Get sms notifications

Endpoint for retrieving the send status of all sms notifications generated by a notification order.

Endpoint

GET /order/{id}/notifications/sms

{id} represents the ID of the notification order to retrieve notifications for.

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.

Response

Response codes

  • 200 OK: The sms notifications were successfully retrieved

  • 404 Not Found: No order matching the provided ID were found

    Refer to problem details in response body for further information.

  • 401 Unauthorized: Indicates a missing, invalid or expired authorization header.

  • 403 Forbidden: Indicates that required scope or Platform Access Token is missing or invalid.

Content-Type

  • application/json

Response body

The response body is formatted as an SmsNotificationSummaryExt and serialized as a JSON string.

Response body properties

orderId

Type: Guid

The ID of the notification order the listed notifications are related to

sendersReference

Type: string

The senders reference the creator provided upon the creation of the notification order

generated

Type: int

The total number of sms notifications generated so far based on the notification order

succeeded

Type: int

The number of sms notifications that have been sent successfully so far

notifications

Type: List<SmsNotificationWithResult>

A list of the generated notifications with send result. Each notification will include the following properties:

  • id: the ID of the notification
  • succeeded: a boolean indicating whether the send status is a successful one.
  • recipient: the contact details of the recipient that the notification is sent to.
  • sendStatus: the send status of the notification.
StatusDescription
NewThe SMS has been created, but has not been picked up for processing yet.
SendingThe SMS is being processed and will be attempted sent shortly.
AcceptedThe SMS has been accepted by the gateway service and will be sent shortly.
DeliveredThe SMS was successfully delivered to its destination.
FailedThe SMS was not sent due to an unspecified failure.
Failed_BarredReceiverThe SMS was not delivered because the recipient’s number is barred, blocked or not in use.
Failed_DeletedThe SMS was not delivered because the message has been deleted.
Failed_ExpiredThe SMS was not delivered because it has expired.
Failed_InvalidRecipientThe SMS was not sent because the recipient number was invalid.
Failed_UndeliveredThe SMS was not delivered due to invalid number or no available route to destination.
Failed_RecipientNotIdentifiedThe SMS was not sent because the recipient’s SMS address was not found.
Failed_RejectedThe SMS was not delivered because it was rejected.

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 Authentication for which one applies to your use case.

curl --location 'https://platform.altinn.no/notifications/api/v1/orders/f1a1cc30-197f-4f34-8304-006ce4945fd1/notifications/sms' \
--header 'Content-Type: application/json' \
--header 'PlatformAccessToken: [INSERT PLATFORM ACCESS TOKEN]' \
--header 'Authorization: Bearer [INSERT ALTINN TOKEN]' 

Response

200 OK

Response body contains the sms notification summary.

{
    "orderId": "f1a1cc30-197f-4f34-8304-006ce4945fd1",
    "sendersReference": "ref-2023-12-01",
    "generated": 1,
    "succeeded": 0,
    "notifications": [
        {
            "id": "e0197ec7-3d82-4917-8329-8c9ecc4c569b",
            "succeeded": false,
            "recipient": {
                "mobileNumber": "+4799999999"
            },
            "sendStatus": {
                "status": "New",
                "description": "The sms has been created, but has not been picked up for processing yet.",
                "lastUpdate": "2023-11-14T16:06:02.877361Z"
            }
        }
    ]
}

404 Not Found

An empty response is returned with the 404 status code.