Send Notifications API V2¶

POST https://secure-{REGION}.id123.io/api/v2/ action: send-notification

New to the API?

Start with the API V2 Introduction for authentication, terminology (IDMS, Card Template, API Key), and a full endpoint list.

Introduction¶

This API is used to send notifications to all cardholders of a particular card template or a single cardholder. Each notification will contain a message displayed as a push notification on the cardholder’s phone. The name of the institution will be in the title of the push notification. When the notification is clicked, the app can display a full message of up to 450 characters, or alternatively, launch a web page in the app.

To send a notification to a specific card user, the “distribution” parameter must be set to “individual” and the “card-id” must be included to identify the card user. The message will be displayed in the App whether or not the person has enabled or disabled notifications. Only iOS users who have “allowed notifications” will receive the push notifications on their lock screen. All Android OS users who have not disabled notifications will receive these push notifications on their lock screen. The “message” field is required and has a maximum length of 100 characters, although all 100 characters may not be displayed in the push notification on the lock screen. Messages over 100 characters are rejected with error F231.

The “url” is required only if the notification is meant to launch a web page when clicked. The “full-message” field is required only if a full page of text is meant to be displayed when the notification is clicked. The “full-message” maximum length is 450 characters. The “url” and “full-message” fields are both optional. If both the URL and Full Message are passed in the request, the URL will have higher precedence and the click will redirect the user to the URL. Please make sure that the URL is valid.

In order to send the same message to all template users, the “distribution” field must be set to “all”. The message will be sent to all users in a specific template defined by the “card-template-id”. Users must have installed the ID card and accepted push notifications to receive the notification. The API must be called for each “card-template-id” separately if your message is intended to be sent to users in more than one card template.

Request Format¶

POST /api/v2/ HTTP/1.1
Host: secure-{REGION}.id123.io
X-API-KEY: API_KEY
Content-Type: application/json

{
   "action": "send-notification",
   "card-template-id": "CARD_TEMPLATE_ID",
   "card-id": "CARD_ID",
   "distribution": "individual", // individual or all
   "notification": {
        "message": "MESSAGE TEXT",
        "full-message": "FULL NOTIFICATION MESSAGE",
        "media": "https://example.com/video.mp4",
        "actions": [
         {
           "url": "https://example.com",
           "label": "Renew Now"
         },
         {
           "url": "https://example2.com",
           "label": "View Details"
         }
       ]
    }
}

Notification Fields¶

Field	Required	Description
`notification.message`	Yes	Push notification text, up to 100 characters (F231 if longer)
`notification.full-message`	No	Text shown when the notification is opened, up to 450 characters (F232 if longer)
`notification.media`	No	A public HTTPS URL to an MP4 video, served as `video/mp4`, shown with the message (F211 otherwise)
`notification.actions`	No	Up to 3 buttons (F236 if more). Each button needs a `label` of up to 50 characters (F263 if longer) and a reachable `url`; F237 if either is missing, F235 if the URL is invalid

Success Response¶

{
    "status": "success",
    "code": "S2006",
    "message": "SUCCESS MESSAGE",
    "card-id": "CARD_ID",
    "card-template-id": "CARD_TEMPLATE_ID"
}

Failure Response¶

{
    "status": "failure",
    "code": "ERROR CODE",
    "message": "ERROR MESSAGE",
    "card-id": "CARD_ID",
    "card-template-id": "CARD_TEMPLATE_ID"
}

Errors¶

This action can return the errors below, as well as the Common API Errors. Placeholders such as {CUSTOM-VALUE-1} are explained in Status Codes.

Status Code	Status Message
F201	`{CUSTOM-VALUE-1}` is required.
F203	Card template was not found.
F204	Invalid value for `{CUSTOM-VALUE-1}` field. Please enter a valid `{CUSTOM-VALUE-2}` value.
F207	Your template is in draft mode. Please approve your template.
F208	Invalid URL. Please provide the full URL address including http:// or https://
F209	Card was not found.
F211	Invalid media URL. Please provide a valid mp4 media url.
F231	Notification Message length cannot exceed 100 characters
F232	Notification Full message length cannot exceed 450 characters
F233	No installed cards available for the template to send notifications.
F234	Card is not installed.
F235	Invalid notification action URL. Provide a valid URL.
F236	Notification exceeds the maximum number of `{CUSTOM-VALUE-1}` actions.
F237	Each notification action requires both a label and a URL.
F252	`{CUSTOM-VALUE-1}` must be greater than current timestamp.
F263	`{CUSTOM-VALUE-1}` exceeds the maximum length of `{CUSTOM-VALUE-2}`.
F268	Message expiration unit is not valid. Allowed units are 'day', 'hour', 'minute'.
F269	Message expiration duration or Message expiration unit is Missing.