logo
API docs by Redocly

Notifications Management API (1.0.9)

Download OpenAPI specification:

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

string or Array of Party ids (strings)
One of
string
Enum: "my" "all"

The preference for target of events. Use my to receive only those events that are relevant to the subscriber organisation. Use all to request to receive all events of the selected type.

Array of objects

Each object in this array defines an attribute filter condition for filtering events. If event matches any of the conditions listed in this array, the message will be delivered to this subscription. Empty array indicates that all messages should be delivered without any filtering.

Each attribute filter condition is a complex object containing one or more key-value pairs representing attribute name and its expected value. The condition will match when all attributes in this condition object have a match in the message payload. A special __not__ keyword allows to specify a negative match for the attribute. An array can also be used instead of a single value, to indicate that the attribute can be equal to any of the values contained in this array.

Not all attributes can be used for filtering. Refer to the schema of each event for details.

Array
status
string
Enum: "Success" "Failure"

Use this attribute to filter by the status of the ONT activation

errorCode
string

Use this attribute to filter by the status of the ONT activation

errorDetails
string

Use this attribute to filter by the errorDetails

errorTitle
string

Use this attribute to filter by the error summary

error
string

Use this attribute to filter by the error message

orderID
string

Use this attribute to filter by the status of the order id

ontSerialNumber
string

Use this attribute to filter by the ONT serial number

opticalStatus
string

Use this attribute to filter by the optical status of an ONT after activation

object (attributes)
required
Array of objects

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

Array
email
required
string <email>
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
Array of objects
Array
email
required
string <email>
Array of objects
Array
callbackUri
required
string <url>

A full url of the webhook (must be https). The Webhook must implement a Notification Webhook API, and support authentication method defined in the auth attribute.

errorStrategy
string
Default: "retry"
Enum: "ignore" "retry" "alarm"

How errors should be handled by the Notification Gateway when there is a problem delivering a message to this channel. All errors, including intermittent connectivity errors, will be handled the same way for all messages on this channel.

  • ignore: Any failed attempt to deliver a message will result in the message being dropped.
  • alarm: Any failed attempt to deliver a message will result in the message being dropped. A notification will be sent to a contact email.
  • retry: Failed messages are retried a certain number of times before being dropped.
required
Basic (object) or API Key (object) or OAuth 2.0 Client Credentials (object) or OAuth 2.0 Password (object)

Responses

Callbacks

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": {
    }
}

Callback payload samples

Callback
POST: Product order notifications
Content type
application/json
Example
{
  • "eventId": "string",
  • "eventTimestamp": "2019-08-24T14:15:22Z",
  • "eventType": "ProductOrderNotification",
  • "message": {
    },
  • "payload": {
    }
}

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

createdFrom
string <date-time>
faker: {"date.past":7}

Optional filter to events generated from a certain point in time. Omitting this sets a default value of now - 7 days (this is also the minimum value for this property).

createdBefore
string <date-time>
faker: {"date.past":0}

Optional filter to events generated before a certain point in time.

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"
}