Notifications API Documentation
Service version: 1
Last edit: 2021.01.15
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
|
|
|
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.
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.