Send Notifications API V2

Send Notifications API V2 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 application can display a message of up to 1000 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 has a maximum length of 100 characters although all 100 characters may not be displayed in the push notification message on the lock screen.  The message field is required and submitting over 100 characters will be truncated. 

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
Content-Length: 852

{  
   "action": "send-notification",
   "card-template-id": "CARD_TEMPLATE_ID",
   "card-id": "CARD_ID",
   "distribution": "individual", // individual or all
   "notification": {
        "message": "MESSAGE TEXT",
        "url": "URL",  
        "full-message": "FULL NOTIFICATION MESSAGE"
    }
}

Success Response

{
    "status": "success",
    "code": "SUCCESS CODE",
    "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"
}

.

.

.