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. A longer message is not rejected: the API shortens it to fit and still sends the notification. The response does not say that the text was shortened.

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. A longer full message is shortened to fit in the same way. 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¶

Send this JSON body to the endpoint above with the headers X-API-KEY: API_KEY and Content-Type: application/json. See API Authentication.

{
   "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",
        "expiration-date": "yyyy-mm-ddThh:mm:ss+00:00", // ISO 8601; or message-expiration-unit and message-expiration-duration
        "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. Longer text is shortened to fit.
`notification.full-message`	No	Text shown when the notification is opened, up to 450 characters. Longer text is shortened to fit.
`notification.media`	No	A public HTTPS URL to an MP4 video, served as `video/mp4`, shown with the message (F211 otherwise)
`notification.expiration-date`	No	When the notification expires, as an ISO 8601 timestamp with a UTC offset, in the format `yyyy-mm-ddThh:mm:ss+00:00`. Must be in the future (F252). `yyyy-mm-dd` and `mm/dd/yyyy` dates are also accepted, with an optional time; other formats return F204. A value with no offset is read as UTC. If you also send a unit and duration, `expiration-date` is used. The F204 and F252 messages name this field `message-expiration`
`notification.message-expiration-unit`	No	`day`, `hour` or `minute` (F268 otherwise). Send it together with `message-expiration-duration` (F269 if only one is sent)
`notification.message-expiration-duration`	No	How long the notification stays valid, counted in `message-expiration-unit`: a whole number from 1 to 60 for `minute`, 1 to 24 for `hour`, or 1 to 365 for `day` (F204 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

How the length limits are counted today

The 100- and 450-character limits are currently counted in bytes, not characters. Accented letters, emoji and non-Latin scripts take more than one byte each, so text that uses them is shortened sooner. For example, a message made only of emoji keeps about 25 of them, and the last character can be cut off. To make sure your text arrives whole, keep it well within the limits.

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.
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.