Notifications API Documentation

The TomTom Notifications API is currently available.

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

Current limits include:

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

Services with endpoints

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

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.

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.

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.