Notifications API Guide
Introduction
This API enables you to send push notifications to end users. This API is ideal for—but not limited to—partners with a connected app. Key features include:
- Contact users via their Fourth ID
Your system does not need to know anything else about the user than their Fourth Account ID, which is available through our workforce management APIs. - Customized messages, in bulk
With just one request you can message up to a thousand end users. The message is customized to each recipient through notification parameters and individual deep links.
Quick Facts
API type | HTTP REST with JSON and XML |
Authentication | OAUTH |
Availability | Available to all partners |
Testing | A test environment is available |
More information | See the API Reference |
Getting started
Follow these steps to integrate.
- Get API credentials and the root URL.
API credentials are linked to customer accounts. Therefore, you must ask any mutual Fourth customers to request credentials for your use. Please ensure they do this as soon as possible. The Fourth Professional Services team member managing the integration can provide you with the root URL and help you with any integration questions you may have. - Create your push notification templates.
This API uses pre-defined templates for your push notifications. The content for each message is customizable through notification parameters.
Once you have decided on the template information, provide this to your Fourth Professional Services team member. They will let you know when the templates are ready to test. - Build and test your integrations.
Connect to the test environment and begin sending push notifications. We recommend testing all of the templates and outcomes you require. You will need to integrate with:- The Notifications API.
- The Fourth Account SCIM API, to retrieve Fourth Account IDs for your recipients.
- Go live!
Updates
You can find any updates on the Release Notes page for the Notifications API.
Creating notification templates
Before integrating with the API, you will need to provide Fourth with your notification templates. These templates define what you want to say.
The simplest template you could provide is one where the Title and Body are both notification parameters. This would allow you to send the full text of the push notification at the time of submission.
The details we need for each notification template are in the next table.
Name | Description |
---|---|
Name |
A name that identifies the push notification template. Type: Unicode string Length: 1-255 characters Example: NewYearNotification |
Title |
The user-visible title in the push notification, similar to a subject line or heading. This field can include notification parameters. Provide the value in curly brackets; for example: {firstname}. Type: Unicode string Length: 40 characters; titles longer than this may be truncated by the mobile phone. Example: Happy New Year, {firstname}! |
Body |
The user-visible description. This field can include notification parameters. Provide the value in curly brackets; for example: {expiry-date}. Type: Unicode string Length: Different mobile phones have different supported lengths, after which a message may be truncated. For maximum compatibility, we recommend limiting the body text to 280 characters. Example: Complete the ‘New Year, New Start’ training by {expiry-date} and get 2 free cinema tickets! |
Example template
Name: NewYearNotification
Title: Happy New Year, {firstname}!
Body: Complete the ‘New Year, New Start’ training by {expiry-date} and get 2 free cinema tickets!
Specifying notification parameters
Notification parameters enable you to set specific values in each request. For example, you may want your notification to show a user's name, the date for a deliver, or the details of a staff event. The parameters the API expects are defined by you, which allows you to display any data that is relevant to your tasks. Fourth will validate this data against your own definitions.
In your API request, the values are set in the Arguments object. For example:
"Arguments": { "firstname": "Jaquin", "expiry-date": "31/01/2020" },
For each task parameter, you need to tell Fourth the following details.
Name | Description |
---|---|
Key |
The key used in your requests to identify the parameter. Type: Unicode string Length: 1-255 Example: firstname |
Value type |
The type of value sent for the key. Options are:
|
For example:
Key | Value type |
---|---|
firstname | String (1) |
expiry-date | DateTime (4) |
Validation of notification parameters
We provide validation for your notification parameters, to check that:
- All parameters specified in the template have a value.
- The correct data type is sent.
If your request doesn't pass this check, then the API will return an HTTP 400 Bad request error.
Specifying deep links
Deep links are the mechanism for linking the push notification to your connected application.
- If you include a deep link, your application opens when the end user taps the notification.
- If you do not include a deep link, then no action occurs when the notification is tapped.
The information you need to include for a deep link is:
- Destination: This is provided by Fourth. It identifies your app in our systems.
- Command: A command name for the action that the deep link triggers.
- Args: A collection of key/value pairs that includes any values you want passed to your connected app.
Our integration team will help you develop your deep links.
Retrieving recipientIds
Every end user of Fourth products, such as Fourth Engage, is given a unique Fourth Account ID. You will need to supply this ID in the recipients array in your requests.
The optimal way for most connected apps to retrieve Fourth Account IDs is via the Fourth Account SCIM API. This API is built to provides user account details for use cases such as user provisioning or messaging. The details it provides includes the user's name, work location and job title.
If, for some reason your application requires more details than the Fourth Account SCIM API can provide, then you will need to integrate with one of the following APIs. Which one you use will depend on where our mutual customer is in business:
-
UK Employee API - use if your customer is using Fourth's UK HR & Payroll solution
-
Labor Productivity API - use if your customer is using standalone Labor Productivity, or are in the US
Before we can provide you with API credentials, your customer will need to provide authorization by contacting their Fourth customer success manager.
Validation of Fourth Account IDs
On submission, we check that the IDs match the format of our Fourth Account IDs. However, we do not check that the IDs are for active accounts, or that the IDs are for people in the mutual customer's employment.
Notifications are only created for recipients who are active employees of the mutual customer. Any non-valid recipients included in the request are ignored.
Connecting to the API
For details about connecting to the API, see the API Reference.
Response from Fourth
Fourth responds to successful requests with an HTTP 200 OK response with an empty response body. This indicates that the request was successfully received and passed validation. After validation, the request is added to a queue of notification requests—this ensures that we can accept and process requests during periods of high load.
We do not report back on whether individual messages reached a mobile phone. There are a variety of factors that influence this.
Troubleshooting
Questions
How do I determine whether messages are received?
While we do everything to ensure that your notifications are successfully sent, there may be instances where an issue occurs between the notification queue and the message sending. To check that your requests are being processed successfully, we recommend:
- Always testing each template and variant with test handsets.
- Including a test handset in any bulk notification requests.
What should I do if I don't receive a response from Fourth?
If you do not receive a response, you should retry your request using a truncated backoff strategy. Please retry requests no more than once a minute. Get in contact with Fourth if you continue to not receive responses.
When considering your retry strategies, it's important to note that if you receive an HTTP transaction timeout, it is still possible that we received the request. Therefore, you should decide whether you'd prefer the end user to potentially receive the message twice, or to not receive the message at all.
Error messages
This API uses standard HTTP response codes.
Example error message
{ "StatusCode": 400, "ErrorCode": 1, "Message": "Validation failed Errors: TemplateId cannot be null or empty.", "Details": [ "TemplateId cannot be null or empty." ], "HelpUrl": "https://developer.fourth.com", "Exception": null }
400 error messages
Fourth ErrorCode | Message | Description |
---|---|---|
1 | Invalid or empty post request body. | The format of the request body is incorrect or the request body is missing. |
1 | Recipients collection cannot be null or empty. | Your request must include at least one recipient. |
1 | {parameter} cannot be null or empty. | One or more mandatory fields is missing a value, or the value is invalid. The error message will specify a list if necessary. |
1 | Invalid TemplateId value. | The template name (templateId) specified was not recognised. If you are unsure of your template names, please get in touch with Fourth. |
1 | Required argument "{notification-parameter}" for "Push" channel and user with Id "{Fourth-Account-ID}" is not provided in the notification message! | A notification parameter is missing or has an invalid value. All notification parameters for a given template are mandatory. Check that the notification parameter is in your request, and if so, that it is spelled correctly and has a value that matches its value type. |