GET /content/notifications

Notifications enable you to recognise what has changed recently. In general, when you begin consuming the notification resource, use the current date and time; if you want to consume historical notifications, please contact your support representative. The response includes a list of Notifications, where each Notification resource represents content that has been modified on or after the values provided in the request; and a list of links, containing the url to use in retrieving the next set of results, so that you don’t miss any changes.

Resource URL

GET https://api.ft.com/content/notifications

Parameters

When you are following the next link from a previous notifications response, you should use that URI without alteration. Otherwise, you can make a request with the following query parameters:

Parameter NameValueRequiredDescription
since datetime yes The start date and time: any content created, updated or deleted since this date should be returned. A valid since parameter must be supplied, and it must be in RFC3339 date time format, for UTC timezone: e.g. 2017-01-06T10:00:00.000Z
The date and time must not be in the future.

Request Body

Do not supply a request body with this method.

Response

HTTP Statuses

Http StatusDescription
200 OK A list of notifications for content that has been updated based on the query parameters supplied. This may be an empty list if no content has changed.
400 Bad Request The request could not be understood by the server due to malformed syntax

200 OK - A list of notifications for content that has been updated based on the query parameters supplied

If successful, this method returns a list of content notifications resources. The maximum number of resources returned in one set of notifications is 200.

The next URL in the links array should be used to retrieve the next set of results.

  • You should not assume that there are no more results because there are fewer than 200 resources. Instead, keep following the next URLs until there are no more notifications.
  • Even if there are no notifications right now, you should still use the next URL when you next poll the notifications API.
  • The next URL will contain query parameters other than since. To avoid gaps and reduce duplicates these should be passed unchanged to the API the next time you call it. If you build your own URL with since, you may miss notifications or receive a large proportion of duplicate notifications.
  • Sometimes you will receive notifications for content that you are not permitted to access. Clients should cope with this situation, for example by ignoring this content and continuing.
  • Sometimes you will receive notifications for content of new types, which have different attributes in the /content endpoint. (For example the bodyXML may not be present.) Clients should cope with this situation, for example by ignoring content they do not understand.
{
  “requestUrl”: string,
  “notifications”: [
    {
      “type”: string,
       “id”: string,
       “apiUrl”: string
    }
  ]  ,
  “links”: [
    {
      “href”: string,
      “rel”: string
    }
  ]
}

Example

E.g. Retrieve the notifications for content changed since 10am UTC on 6th January 2017

GET http://api.ft.com/content/notifications?apiKey=yourApiKey&since=2017-01-06T10:00:00.000Z
{
  “requestUrl”: “http://api.ft.com/content/notifications?since=2017-01-06T10:00:00.000Z",
  “notifications”: [
    {
      “type”: “http://www.ft.com/thing/ThingChangeType/UPDATE",
      “id”: “http://www.ft.com/thing/7348edd8-0403-11de-845b-000077b07658",
      “apiUrl”: “http://api.ft.com/content/7348edd8-0403-11de-845b-000077b07658"
    }
  ],
  “links”: [
    {
      “href”: “http://api.ft.com/content/notifications?since=2017-01-06T18:42:35.000Z&page=MjAxNy0wMS0wNlQxODo0MjozNVojMCMxMjM0NTY3OA==",
      “rel”: “next”
    }
  ]
}