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.

  1. Contact Fourth.
    Our implementation consultants will:
    • Provide you with the URL for a test environment.
    • Help you with any questions.
  2. Request API credentials.
    API credentials are linked to customer accounts. Therefore, you must ask any mutual Fourth customers to request credentials for your use.
  3. 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 implementation consultant. They will let you know when the templates are ready to test.
  4. 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.
    • A Fourth workforce management API (to retrieve Fourth Account IDs for your recipients).
  5. Go live!

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 push notification shown on a mobile phone.

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:

  • Boolean (0)
  • String (1)
  • Integer (2)
  • Double (3)
  • DateTime (4)
  • Format options are:
    • DD/MM/YYYY
      For example: 13/01/2019
    • YYYY-MM-DDThh:mm:ss.sTZD
      For example: 2018-12-19T07:05:14.604Z

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.

There are two APIs available for retrieving the Fourth Account IDs of users. Which one you use will depend on the mutual customer's business location.

  • UK Employee API—use if your customer is using Fourth HR & Payroll in the UK

  • Labor Productivity API—use if your customer is using Fourth Labor Productivity 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 recieved 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

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.