logo
API docs by Redocly

Notifications Management API (1.0.9)

Download OpenAPI specification:Download

E-mail: api@tuatahifibre.co.nz

This API is for RSPs and SPs to subscribe to notifications for a variety of Tuatahi events.

In order to start receiving notifications, the consumer must choose a suitable notification channel. Following notification channels are supported:

  • email. This channel is suitable for low volume, losely structured events.
  • webhook. This channel is suitable for all event types. The subscriber must implement a Webhook API which TFF will use to deliver the payload of the selecte events.

Subscriptions

Get all subscriptions

Gets all the subscriptions associated with the given consumer. Consumer is identified through the partyId claim in the access token.

Authorizations:
OAuthOAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new subscription

Creates new subscription for a specified Event type. Subscription is linked to the consumer which is identified through the partyId claim provided in the access token

Authorizations:
OAuthOAuth
Request Body schema: application/json
required
One of
eventType
required
string
Value: "ONTActivation"

The type of event to subscribe to

object

The scope of what events to receive

required
Array of objects

The emails to send any updates about subscriptions to. E.g. when a subscription is about to expire

expiresOn
string <date>

The date the subscription expires in ISO 8601, e.g. yyyy-MM-dd. The max date this can be is 1 year in the future. If the date passed is more than 1 year in the future or no date is passed then the date 1 year in the future is used. If no timezone is added to the date the assumed timezone is nz time (adjusting for whether the date is daylight time or not)

object

Responses

Request samples

Content type
application/json
Example
{
  • "eventType": "ONTActivation",
  • "filters": {
    },
  • "contactEmails": [
    ],
  • "expiresOn": "2019-08-24",
  • "notificationChannels": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "eventType": "string",
  • "filters": {
    },
  • "contactEmails": [
    ],
  • "expiresOn": "2019-08-24",
  • "clientId": "string",
  • "organisation": "string",
  • "partyIds": [
    ],
  • "notificationChannels": {
    }
}

Partially update an existing subscription

Partially updates an existing subscription referenced by its unique ID. Subscription is linked to the consumer which is identified through the partyId claim provided in the access token

Authorizations:
OAuth
path Parameters
id
required
string <uuid>

Unique ID of an existing subscription

Request Body schema: application/json
required

Subscription properties that currently support partial updates. At least one property must be set

expiresOn
string <date>

The date the subscription expires in ISO 8601, e.g. yyyy-MM-dd. The max date this can be is 1 year in the future. If the date passed is more than 1 year in the future then the date is set to 1 year in the future. If no timezone is added to the date the assumed timezone is nz time (adjusting for whether the date is daylight time or not)

Responses

Request samples

Content type
application/json
{
  • "expiresOn": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "eventType": "string",
  • "filters": {
    },
  • "contactEmails": [
    ],
  • "expiresOn": "2019-08-24",
  • "clientId": "string",
  • "organisation": "string",
  • "partyIds": [
    ],
  • "notificationChannels": {
    }
}

Get a subscription

Gets the subscription

Authorizations:
OAuthOAuth
path Parameters
subscriptionId
required
string <uuid>

Unique ID of the subscription

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "eventType": "string",
  • "filters": {
    },
  • "contactEmails": [
    ],
  • "expiresOn": "2019-08-24",
  • "clientId": "string",
  • "organisation": "string",
  • "partyIds": [
    ],
  • "notificationChannels": {
    }
}

Delete a subscription

Deletes a subscription

Authorizations:
OAuthOAuth
path Parameters
subscriptionId
required
string <uuid>

Unique ID of the subscription

Responses

Response samples

Content type
application/json
{
  • "statusCode": 401,
  • "message": "Unauthorized"
}

Notifications

Replays notifications by a query specification

Enables the ability to bulk replay notifications by a query specification.

Authorizations:
OAuthOAuthOAuth
Request Body schema: application/json
id
string <uuid>

Optional filter to a specific notification identifier.

status
string
Enum: "sent" "fail"

Optional filter to notifications in the specified status. Omitting this will result in a default value of 'fail'.

object

Optional filter to attributes describing the source event

limit
required
number >= 1

Required parameter which limits the number of notifications that will be sent. The maximum number of notifications that can be replayed at once is set by TFF at the system level.

clientId
string

Optional filter to notifications for a specific clientId. Omitting this will result in the service using the clientId from your token.

organisation
string

Optional filter to notifications for a specific organisation. Omitting this will result in the service using the organisation from your token.

dryRun
required
boolean

Required parameter which allows for a dry-run without the commitment of actually executing notifications. Note: Due to notifications being in a constant state of change, there is no guarantee that the same request, with 'dryRun: false', would replay the same notifications.

Responses

Request samples

Content type
application/json
Example

Illustrates how to identify the number of failed notifications without committing to a replay. It is a safe way to test the potential impact of a given request. Note: Due to notifications being in a constant state of change, there is no guarantee that the same request, with 'dryRun: false', would replay the same notifications.

{
  • "status": "fail",
  • "limit": 1000,
  • "dryRun": true
}

Response samples

Content type
application/json
Example

An example of a dry-run result. It indicates that 1 notification would be sent.

{
  • "id": "2f31838e-d24f-4af1-bc43-c3af992da39e",
  • "request": {
    },
  • "results": {
    }
}

Replays notifications by a notification ID

Enables the ability to bulk replay notifications by a notification ID. Useful if you know if a specific notification that you want to replay.

Authorizations:
OAuthOAuthOAuth
path Parameters
id
required
string <uuid>
Example: 322e1915-768d-48a9-8b3b-4332317b1107

Responses

Response samples

Content type
application/json

An example of a date range result which also provides surface-level information for tracing. The sample indicates only 1 notification in the time range was found, and therefore only 1 was queued for sending successfully.

{
  • "id": "745ad5ed-0560-4c9a-bf09-6fa894808117",
  • "replayId": "0d5cc1a1-fd6f-40b1-9fbf-46e483869cd7",
  • "status": "Queued"
}