Introduction

What is TomTom's Notifications API?

The Notifications API and its services provides the ability to read and clear the history of sent notifications. If you wish to stop receiving any notifications from the Notifications API services, please contact our Support and provide the address you wish to unsubscribe. See the Contact Groups documentation page for further information on the Contact Groups API. TomTom's Notifications service is intended to manage communication from Maps APIs to users. The following means of contact are supported:

• webhooks
• e-mails

Current limits include:

• 20 webhook addresses per Contact Group.
• 20 e-mail addresses per Contact Group.

Benefits of using the Notifications API

The main benefit of choosing contact groups is that it can contain a single address or multiple addresses. When the same contact group has been used in multiple APIs and a change occurs in the way of communication in this group, then this change will appear in all APIs where this group is being used.

Services with endpoints

Getting started

1. To get your API Key, you first need to be registered for the TomTom Developer Portal. If you don't have an account, no worries! Register / Sign in now before continuing.
2. Once you are registered, go to your Dashboard and locate the API Key that you would like to use (we've created the first one for you, it's called My first API Key).
3. Read the documentation and start coding.
4. Consider using the TomTom Maps SDK for Web , for iOS , and for Android.
5. Check related Blog articles for further information.

Follow these steps to start working with the Notifications API.

Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Step 1. Register for an API Key

You need to have an API Key to work with Notifications. This allows you to work with any TomTom Maps API, including Notifications. This key will let you read data from the service, such as notification history.

Step 2. Create a Contact Group

A Group must be added with at least one way to send notifications. A Group is created using the Group service Create contact group endpoint.

URL example

1https://api.tomtom.com/notifications/1/groups?key={Your_API_Key}
2{
3  "name": "A contact group name",
4  "webhookUrls": ["http://www.example.com/"]
5}

curl command example

1curl -XPOST "Content-type: application/json" -d
2'{
3  "name": "A contact group name",
4  "webhookUrls": ["http://www.example.com/"]
5 }'
6'https://api.tomtom.com/notifications/1/groups?key={Your_API_Key}'

The endpoint returns contact group details including a group id.

Response body

1{
2  "id": "715c17e3-b5b8-47c7-ba0d-b2873f1dca1e",
3  "name": "Tutorial group",
4  "webhookUrls": ["http://www.example.com/"]
5}

This group id can be used for future calls (i.e., editing or deleting a group).

Step 3. Receive notification

Notifications can be sent by other TomTom services. They only need the id of the group which should receive notifications.

When notification has been received

Managing notifications

You need to have an API Key to work with Notifications. This allows you to work with any TomTom Maps API, including Notifications.

Follow these steps to start working with the Notifications API.

Step 1. Get notifications history

Notifications that have been sent by TomTom Services can be listed by using the List notifications history endpoint. History is kept for 7 days and after that time it will be automatically deleted.

URL format

https://api.tomtom.com/notifications/1/history?key={Your_API_Key}&from={TIMESTAMP}

The endpoint returns a list of the sent notifications.

curl command format

curl 'https://api.tomtom.com/notifications/1/history?key={Your_API_Key}&from={TIMESTAMP}'

TMESTAMP is an ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss), for example 2020-05-01T19:37:00.

Response body

1{
2  "summary": {
3    "from": "2020-05-01T19:37:00",
4    "to": "2020-05-02T19:37:00"
5  },
6  "notifications": [
7    {
8      "title": "Tutorial",
9      "body": "How to use notifications",
10      "contact": {
11        "type": "GROUP",
12        "value": "715c17e3-b5b8-47c7-ba0d-b2873f1dca1e"
13      },
14      "status": {
15        "type": "SUCCESS",
16        "details": "OK"
17      },
18      "sendDate": "2020-05-01T21:03:46+0000"
19    }
20  ],
21  "resultInfo": {
22    "maxResults": 100,
23    "pageNumber": 1,
24    "itemsCount": 1
25  }
26}

Step 2. Clear notifications

Notification history can be cleared by using Clear notifications history endpoint.

URL example

https://api.tomtom.com/notifications/1/history?key={Your_API_Key}

curl command example

curl -XDELETE 'https://api.tomtom.com/notifications/1/history?key={Your_API_Key}'

Response body

1{
2  "deleteAllHistoryMessagesBefore": "2020-05-01T19:37:00",
3  "deleteAllHistoryMessagesBeforeStatus": "PROCESSING"
4}

This means that the clearing of notifications history has been started. All notifications before 2020-05-01T19:37:00 will be deleted.