TomTom LogoDocs
Products
Resources
Pricing
Sign in
Notifications API

List notifications history

Service version: 1Last edit: 2022.08.30

Decommission notice

December 16, 2025

  • This service will be decommissioned on January 31, 2027.
  • All endpoints will be withdrawn following a 12 months deprecation period.
  • There is no recommended migration path.

Purpose

This endpoint provides a history of notifications. As notification history entries have a TTL of 7 days, you cannot check further back in the history. The list is sorted from the freshest to the oldest.

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL request format

get
URL request format
https://{baseURL}/notifications/{versionNumber}/history?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}

curl command request format

get
curl command request format
curl 'https://{baseURL}/notifications/{versionNumber}/history?key={Your_API_Key}&from={timestamp}&to={timestamp}&maxResults={integer}&pageNumber={integer}'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Required parameters

Description

baseURL


string

The base URL for calling the API.


Value: api.tomtom.com

versionNumber


string

Service version.


Value: 1

key


string

An API Key valid for the requested service.


Value: Your valid API Key.

from


timestamp

Beginning date for the listing.


Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss).

Optional parameters

Description

to


timestamp

End date for the listing.


Value: ISO 8601 format timestamp with the accuracy of seconds (YYYY-MM-DDThh:mm:ss).

maxResults


integer

Maximum number of items returned in the response.


Value: Greater than zero, less than or equal to 100.


Default: 100

pageNumber


integer

The number of items on the page to be returned in the response. The maximum number of elements on the page is equal to the maxResult value.


Value: Greater than zero.


Default: 1

Response data

Response body

Response body example - JSON
{
  "summary": {
    "from": "ISO8601_timestamp",
    "to": "ISO8601_timestamp"
  },
  "notifications": [{
      "title": "message title",
      "body": "message body",
      "contact": {
        "type": "contact_type",
        "value": "contact"
      },
      "status": {
        "type": "status_type",
        "details": "status_details"
      },
      "sendDate": "creation_timestamp"
    },
    ...
  ],
  "resultInfo": {
    "maxResults": 100,
    "pageNumber": 1,
    "itemsCount": 100
  }
}

Response fields

The following table describes all of the fields that can appear in a response.

Primary fields

Field

Description

summary


object

Contains information about the timestamps from , to.

notifications


array

Contains information about notifications.

resultInfo


object

Contains information about response paging.

summary object

Field

Description

from


string

Timestamp (ISO 8601 format) marking the start of a period the report is generated for.

to


string

Timestamp (ISO 8601 format) marking the end of a period the report is generated for.

notification array

Field

Description

title


string

Notification title.

body


string

Notification body.

contact


object

Object representing a contact to which this notification has been sent.

status


status

Object representing the outcome of the notification being sent.

sendDate


timestamp

The time when an entry was created, which is also the time when the notification was sent.

contact object

Field

Description

type


string

Contact type: WEBHOOK or EMAIL.

value


string

Actual contact string.

status object

Field

Description

type


string

Either SUCCESS or FAILURE.

details


string

OK for SUCCESS or description for FAILURE :

  • WEBHOOK : The HTTP response code and returned message.

  • EMAIL : The send status.

resultInfo object

Field

Description

maxResult


integer

Maximum number of items returned in the response.

pageNumber


integer

Number of the items page to be returned in the response. Maximum number of elements on the page is equal to the maxResult value.

itemsCount


integer

Number of returned items on the page.

Response codes

Code

Meaning & possible causes

200

OK

400

Bad Request : Wrong datetime format.

Example

List all sent notifications.

Request URL

get
URL request example
https://api.tomtom.com/notifications/1/history?key={Your_API_Key}&from=2020-05-01T02:00:00&to=2020-05-01T20:00:00

Response body

The following JSON code block demonstrates a successful response from the API server.

Response body example - JSON
{
  "summary": {
    "from": "2020-05-01T02:00:00+0000",
    "to": "2020-05-01T20:00:00+0000"
  },
  "notifications": [
    {
      "title": "Message 1 title.",
      "body": "Message 1 body.",
      "contact": {
        "type": "WEBHOOK",
        "value": "URL_INVALID"
      },
      "status": {
        "type": "FAILURE",
        "details": "WEBHOOK format is invalid"
      },
      "sendDate": "2020-05-01T18:52:51+0000"
    },
    {
      "title": "Message 2 title.",
      "body": "Message 2 body.",
      "contact": {
        "type": "WEBHOOK",
        "value": "http://example.com/example"
      },
      "status": {
        "type": "SUCCESS",
        "details": "OK"
      },
      "sendDate": "2020-05-01T14:03:46+0000"
    }
  ],
  "resultInfo": {
    "maxResults": 100,
    "pageNumber": 1,
    "itemsCount": 2
  }
}