Sorry, you need to enable JavaScript to visit this website.

Notifications API Documentation

 

Service version: 1
Last edit: 2020.05.21

The TomTom Notifications API is currently available.

On this page

Purpose

What is TomTom's Notifications service?

TomTom's Notifications service is intended to manage communication from Maps APIs to users.

Following means of contact are supported:

  • webhooks
  • e-mails

Features

Current limits include:

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

Services with endpoints

Configuration service
The Configuration service is used to work with your account and provides list statuses and settings.
GETList current options
Contact Groups service
The Contact Groups service provides means for managing contact groups.
POSTCreate contact group
GETList contact groups
GETGet contact group details
PUTEdit contact group
PATCHEdit contact group partially
DELETEDelete contact group
Notifications History service
The Notifications service provides the ability to read and clear the history of sent notifications.
GETList notifications history
DELETEClear notifications history

▲ Return to top

Interactions with other APIs

  • The Notifications API and access for other TomTom APIs is defined as follows.
    • Each API can send messages to the contact group but they don't have an explicit access to them.
    • Other APIs cannot view or modify the content of the 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.

Quick start guide

Configuration

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

Getting started

Follow these steps to start working with the Notifications API:

Step 1. Register for an API Key

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 format

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

curl command

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

The endpoint returns contact group details including a group id.

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

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.

▲ Return to top

When notification has been received

Managing notifications

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

Getting started

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 "List notifications history". 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

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.

Example Response body

{
      "summary": {
        "from": "2020-05-01T19:37:00",
        "to": "2020-05-02T19:37:00"
      },
      "notifications": [{
        "title": "Tutorial",
        "body": "How to use notifications",
        "contact": {
          "type": "GROUP",
          "value": "715c17e3-b5b8-47c7-ba0d-b2873f1dca1e"
      },
      "status": {
        "type": "SUCCESS",
        "details": "OK"
      },
      "sendDate": "2020-05-01T21:03:46+0000"
      }],
      "resultInfo": {
        "maxResults": 100,
        "pageNumber": 1,
        "itemsCount": 1
      }
}

Step 2. Clear notifications

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

URL format

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

curl command

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

Example Response body

{
    "deleteAllHistoryMessagesBefore": "2020-05-01T19:37:00",
    "deleteAllHistoryMessagesBeforeStatus": "PROCESSING"
}

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

▲ Return to top