logo
API docs by Redocly

Connect API (v1.0.21)

Download OpenAPI specification:Download

E-mail: api@tuatahifibre.co.nz

Product Offer Catalogue

Get all product offers codes

Returns the full TFF Product Offer Catalogue that is applicable to a given customer.

Authorizations:
OAuth
query Parameters
customerId
required
string

The Customer ID for a customer e.g. the partyId for an RSP

Responses

Response samples

Content type
application/json
{
  • "customerId": 1,
  • "customerName": "Spark",
  • "productOffers": [
    ]
}

Get a product offer

Returns the complete Product Offer details (i.e. including all Product Offer Configurations) for a TFF Product Offer for a given customer.

Authorizations:
OAuth
path Parameters
offerCode
required
string

The code for a given offer

Responses

Response samples

Content type
application/json
{
  • "offerCode": "B2U-HR30M10M",
  • "name": "Bitstream 2 Ultra Headline Rate 30M/10M",
  • "description": "A Bitstream 2 Ultra Product Offer with a Headline Rate of 30 Mbps / 10 Mbps",
  • "validFor": "2019-08-24",
  • "status": "Active",
  • "isForSaleStandalone": true,
  • "categoryCode": "BS2ULTRA",
  • "productOfferRelationships": [ ],
  • "productOfferConfigurations": {
    },
  • "productOfferCharacteristics": [
    ]
}

Get a product offer configuration

Returns the complete Product Offer Configuration details for a TFF Product Offer Configuration for a given customer.

Authorizations:
OAuth
path Parameters
offerCode
required
string

The code for a given offer

configurationCode
required
string

The code for a given offer configuration

Responses

Response samples

Content type
application/json
{
  • "configurationCode": "string",
  • "name": "string",
  • "description": "string",
  • "validFor": "2023-01-30",
  • "targetSegments": [
    ],
  • "productOfferConfigurationHierarchy": [
    ]
}

Search a place via autocomplete style

Returns places and locations matching the user input. Use this method in "search as you type" scenarios, e.g. with autocomplete UI elements

This search will attempt to match every token from the user input against the core fields of the address - street name, street number, unit, town, etc. The match of each word is partial (i.e. prefix). If there is more than one word (token) in the search query, only addresses that have a match for all tokens will be returned.

Authorizations:
OAuth
query Parameters
q
required
string

User input as plain text (i.e. search query)

size
integer
Default: 10

Optional, the maximum number of results to return. This should be used for paginating search result. Default is 10 results per page.

from
integer
Default: 0

Optional, number of hits to skip. This should be used in combination with size for paginating search result. Default is 0 (first page). To request a second page, set this attribute to the value matching your size, e.g. 10

searchFields
string
Enum: "tui" "dpid" "placeId" "legacyLocationId" "ontSerialNumber"

This parameter is used to request a search by the exact match on a specified field. Use this parameter to find a place by TUI, DPID, PlaceId, LegacyLocationId or ONT Serial Number.

unitPosition
any
Default: "adaptive"
Enum: "strict" "adaptive"

Controls whether search for “65/12” should be interpreted strictly as 65 being the unit number. Alternative is to search adaptively for either 65 or 12 in any field. Note that using adaptive option will increase the number of matches, but the relevance may not be as accurate. E.g. adaptive option will match addressed with “12/65” or “65 SH 12“.

suffixMatch
any
Default: "off"
Enum: "off" "adaptive"

This is an experimental option. When its set to off, searching in the street number suffix field separately from street number is disabled. E.g. search query 'D' will not match addresses with street number suffix D such as '50D' or '1D'). The adaptive option will search for 'D' in the street number suffix field, but the side effect is that it will also match all street names starting with 'D'. With either option, searching for '50D' will match addresses with '50D' (street number '50' and street number suffix 'D').

searchPostcode
any
Default: "off"
Enum: "off" "adaptive"

This is an experimental option. When its set to off, searching in the Postcode field is disabled. Due to the nature of autcomplete matching by prefix, many '1-', '2-', or 3-character street numbers will match a postcode, and this will produce a lot of noise in the results. Use adaptive option to instruct API to execute a secondary search with postcode only if there was no match from the first search.

includeDetails
boolean
Default: false

If set to true, the response will include additional details about the place, such as legal description, TUI, and unit number.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "level": 0,
  • "hits": [
    ]
}

Regular search

Returns places and locations matching the search criteria.

This search will attempt to match any token from the user input against the core fields of the address - street name, or street number, unit, town, etc. The token is considered a match if it matches the full word in the address field, e.g. “Lak” will not match “Lake”.

This method can be used independently or in combination with autocomplete. A typical usage is to execute this search only after autcomplete hasnt yielded any results.

Authorizations:
OAuth
query Parameters
q
required
string

User input as plain text (i.e. search query)

size
integer
Default: 10

Optional, the maximum number of results to return. This should be used for paginating search result. Default is 10 results per page.

from
integer
Default: 0

Optional, number of hits to skip. This should be used in combination with size for paginating search result. Default is 0 (first page). To request a second page, set this attribute to the value matching your size, e.g. 10

searchFields
string
Enum: "tui" "dpid" "placeId" "legacyLocationId" "ontSerialNumber"

This parameter is used to request a search by the exact match on a specified field. Use this parameter to find a place by TUI, DPID, PlaceId, LegacyLocationId or ONT Serial Number.

includeDetails
boolean
Default: false

If set to true, the response will include additional details about the place, such as legal description, TUI, and unit number.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "level": 0,
  • "hits": [
    ]
}

Service Qualification

Service Qualification

Returns products available at this location

Authorizations:
OAuth
path Parameters
placeId
required
string
Example: 40186274UFFLC3B
query Parameters
activeInventoryOnly
boolean

Enables filtering to results where the associated product inventory status is active. If this is unspecified or true, then it returns active inventory only. If you want inactive inventory then explicitly set to false.

Responses

Response samples

Content type
application/json
{
  • "serviceAvailableDate": "2019-08-24",
  • "placeServiceability": "Serviceable",
  • "fdhAvailableDate": "2019-08-24",
  • "fdhRegionName": "HW_95727",
  • "networkRegionName": "WKO",
  • "handoverLocation": "HMW",
  • "fdhState": "string",
  • "activeProducts": [
    ],
  • "inventory": [
    ],
  • "availableProducts": [
    ]
}

Orders

Returns the list of Handover Connection Interface

Returns the list of Handover Connection Interface Group related for a given customer.

Authorizations:
OAuth
query Parameters
customerId
required
string

The Customer ID for a customer e.g. the partyId for an RSP

Responses

Response samples

Content type
application/json
{
  • "customerId": 0,
  • "customerName": "string",
  • "dateListCreated": "2021-03-01T17:32:28Z",
  • "HandoverConnectionInterfaceGroupList": [
    ]
}

Place an order

Places a new Customer Product Order into TFF ordering portal. This API supports following order types:

  • New Product (new service at the end-user premises)
  • Change Product (change to the existing service at the end-user premises)
  • Terminate Product (terminate existing service)
  • Pre-Install (connect end-user premises to the TFF fibre network)

If the API call is successful, returns the Customer Product Order identifier that has been created in the TFF ordering portal (e.g. Telflow).

Scenario: Product Attributes Change

A 'Configuration Change' is possible by creating a 'Change Product Order' and specifying the target attributes of the product, along with the appropriate offer code and configuration code. The exceptions are CVLAN/SVLAN and ONTPN which are enriched from the inventory systems.

Scenario: Product Family Change

An 'Intact - Product Family Change' is achieved by creating a 'Change Product Order' order and identifying the new target product. All attributes for the target state of the product should be provided. The exceptions are CVLAN/SVLAN and ONTPN which are enriched from the inventory systems.

Some product family changes have the CVLAN / SVLAN re-allocated asynchronously; those attributes are shared outside of the order creation flow and are part of the provisioning process.

Authorizations:
OAuth
query Parameters
customerId
required
string

The Customer ID for a customer e.g. the partyId for an RSP

Request Body schema: application/json
required
One of
dateTimeSubmitted
required
string <date-time> (value.OrderSubmissionTime)

The submission date and time of this order in ISO-8601 format.

handoverConnectionInterfaceGroupId
required
string

The ID of a Handover Connection Interface Group for that Customer i.e. from Get HandoverConnectionInterfaceGroup.

externalId
required
string

Customer reference

note
string

A note to capture comments that the customer may want to share with TFF concerning this New Customer Product Order.

object (request.BaseNewProductOrder.commitment)

Describes the commitment (i.e. for service to be delivered) that is expected by the customer / end-customer.

required
object (request.BaseNewProductOrder.siteDetails)

Provides the required details about the end-customer premise / site.

required
Array of objects (request.BaseNewProductOrder.productOffer)

Describes the product offer (one or more) that the customer has selected as part of this Customer Product Order.

required
object (request.BaseNewProductOrder.projectDetails)

Provides the required details about the project to which this Customer Product Order may relate.

notificationOwner
string (value.NotificationOwner)

The receiver of email notifications for this order. This is username as reported from the TFF ordering portal (Telflow)

An authorisation check is performed on this so that notifications are not erroneously set to users not related to the authenticated organisation e.g. if the token is for RSP-A party but the username is part of RSP-B's party, then an error will be returned describing an authorisation problem.

Credentials which have multiple parties associated to it must explicitly specify a customerId in the query string to resolve ambiguity around which party the order is being placed on behalf of.

If a notification owner is not specified then email notifications will not be sent.

orderType
required
string
Value: "New"
object

Describes the details of the Fibre connection that is being ordered

required
object (request.BaseNewProductOrder.endCustomerDetails)

Provides the required details about the end-customer.

Responses

Request samples

Content type
application/json
Example
{
  • "dateTimeSubmitted": "2021-03-01T17:32:28Z",
  • "handoverConnectionInterfaceGroupId": "string",
  • "externalId": "KT-008-01",
  • "note": "string",
  • "commitment": {
    },
  • "siteDetails": {
    },
  • "productOffers": [
    ],
  • "projectDetails": {
    },
  • "notificationOwner": "string",
  • "orderType": "New",
  • "connectionDetails": {
    },
  • "endCustomerDetails": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "externalId": "string",
  • "orderDate": "2019-08-24T14:15:22Z",
  • "orderType": "New",
  • "customerId": "66523",
  • "expectedCompletionDate": "2019-08-24T14:15:22Z",
  • "connectionType": "New Build",
  • "state": "Acknowledged",
  • "note": [
    ],
  • "hasPendingOperations": true
}

List or search orders

Returns the Customer Product Order

Authorizations:
OAuth
query Parameters
size
integer
Default: 50

Optional, the maximum number of results to return. This should be used for paginating list results. Default is 50 results per page.

from
integer
Default: 0

Optional, number of results to skip. This should be used in combination with size for paginating list result. Default is 0 (first page). To request a second page, set this attribute to the value matching your size, e.g. 50

customerId
string

The Customer ID for a customer e.g. the partyId for an RSP

progress
string
Enum: "open" "held" "closed"

Select orders is a particular state. E.g. open will include orders that are Acknowledged or In Progress.

actionRequired
boolean
Value: true

To list all orders requiring action from RSP, use this attribute with true

externalId
string

Filter orders by the customer's external Id

productId
string^[A-Z0-9]{15}$

Filter orders by the Product Id

placeId
string^\d{8}UFFL[a-zA-Z0-9]+$
Example: placeId=90000000UFFLA00

The place ID to narrow the list down to

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "orders": [
    ]
}

Get order details

Returns the Customer Product Order

Authorizations:
OAuth
path Parameters
orderId
required
string

Unique ID of the activation

query Parameters
customerId
string
Example: customerId=66450

The Customer ID for a customer e.g. the partyId for an RSP

expand
string
Example: expand=quotes

A CSV separated list of object subkeys to expand and include in the query. The available options are:

  • quotes

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "externalId": "string",
  • "orderDate": "2019-08-24T14:15:22Z",
  • "orderType": "New",
  • "customerId": "66523",
  • "expectedCompletionDate": "2019-08-24T14:15:22Z",
  • "connectionType": "New Build",
  • "state": "Acknowledged",
  • "note": [
    ],
  • "hasPendingOperations": true,
  • "quotes": [
    ],
  • "contractor": "string",
  • "action": [
    ],
  • "cancellationDate": "string",
  • "connectionDetails": {
    },
  • "products": [
    ],
  • "productOffers": [
    ]
}

Perform an operation on an order

Performs an operation on an existing Customer Product Order using the TFF ordering portal. This API supports the following operations:

  • Cancel an Inflight Order
  • Amend the RFS date for an Inflight Order
  • Amend the Product Offer for an Inflight Order
  • Add or Change ATA for an Inflight Order
  • Remove ATA for an Inflight Order
  • Add or Change Premises Networking for an Inflight Order
  • Change Product Offer Characteristics for an Inflight Order
  • Change Contact Details for an Inflight Order
  • Responding to a Transfer Order
Authorizations:
OAuth
query Parameters
customerId
required
string

The Customer ID for a customer e.g. the partyId for an RSP

Request Body schema: application/json
required
op
required
string
required
object (request.CancelInflightOrderPayload)

Provides the information required to cancel an inflight Customer Product Order.

Responses

Request samples

Content type
application/json
Example
{
  • "op": "CancelInflight",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "statusCode": 400,
  • "error": "Input Validation error",
  • "message": "Input Validation error"
}

Add a note to an order

Add a customer facing note to an existing customer order and optionally request action from TFF.

Authorizations:
OAuth
Request Body schema: application/json
required
text
required
string

The note text to submit against the order.

author
required
string

The name of the author for trace and ownership purposes. This name will be presented in the destination systems user interface (qualified with authenticated organisation information.)

customerId
number

The customer's Telflow organisation/customer id for stamping the note with an authenticated organisation name. The token must have access to the customer in its claims (useful for tiered organisation structures.)

When the token has a single party ID associated to it, the API will infer this customer id and it can be omitted from the payload as not required.

activity
string
Value: "ActionRequested"

Optional, the activity type of the note. This is used to determine the type of note that will be created in the destination system. The following activity types are supported:

ActionRequested - When the note is created with this activity type, it will be treated as a request for action from TFF.

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "author": "string",
  • "customerId": 0,
  • "activity": "ActionRequested"
}

Response samples

Content type
application/json
{
  • "statusCode": 400,
  • "error": "Input Validation error",
  • "message": "Input Validation error"
}

List orders that require action by an RSP

Returns limited details for any order that requires action by an RSP.

Authorizations:
OAuth
query Parameters
type
required
string
Value: "RespondToTransfer"
customerId
string
Example: customerId=66450

The Customer ID for a customer e.g. the partyId for an RSP

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "orders": [
    ]
}

Reports

Stream a Product Inventory Report

This endpoint reports on product inventory, and typically advises about the status of the inventory in one of many reporting modes. The modes of operation cater to reporting now or last month for a particular TFF RSP customer, to assist with periodically reconciling records in an automated fashion.

The API uses Server Sent Events (SSE) to stream the results to clients. SSE is a simple technique which the client opens a socket, and TFF delivers line-delimited JSON results to that socket as they are ready. The server will close the socket when there is no more data to consume. SSE enables the results to be collected as they are ready and a reference standard, instead of blocking for a longer period of time and/or implementing a custom paging mechanism.

Authorizations:
OAuth
query Parameters
mode
required
any
Enum: "active-now" "active-last-month"

Determines the mode of operation for this reporting endpoint.

  • active-now: Product inventory items that are active now; if customer data is changing this will update live. Useful for reporting on a reasonable defintion of now [1]

  • active-last-month: Product inventory items that were active in the last month; that is: data constrained to the last calendar month. Useful for reporting on a monthly basis.

    This is semi-stable i.e. successive calls should expect to return the same data until the definition of last month changes (e.g. a transition from March to April.)

[1]: There are some uncontrollable caching factors that may influence this. We make no guarantees about how often the cache is refreshed. Please consult with API product owner if you have special API needs relating to this.

customerId
any

Enables control of the customer ID to query for in a multi-customer token. If the token only has a single customer ID associated to it, then the API will use that.

Responses

Response samples

Content type
text/event-stream
{"customerId":1,"inventory":[{"id":"UFF000000000001","placeId":"40000000UFFL001","legacyPiid":"UFFABCHM0000001","legacyLocationId":"0012345600HW1AB","igPiid":"UFF100000000001","status":"Active","contractStartDate":"2023-01-01T15:00:00.000+12:00","productOfferName":"Bitstream 2 Ultra 50/10 2.5/2.5"},{"id":"UFF000000000002","status":"Active","contractStartDate":"2023-01-02T18:00:00.000+12:00","productOfferName":"Bitstream 2 Ultra 50/20 2.5/2.5"}]}
{"customerId":1,"inventory":[{"id":"UFF000000000003","placeId":"40000003UFFL003","legacyPiid":"UFFDEFHM0000003","legacyLocationId":"0023456700HE1CD","igPiid":"UFF300000000003","status":"Inactive","contractStartDate":"2022-12-01T15:00:00.000+12:00","productOfferName":"Bitstream 2 Ultra 50/10 2.5/2.5","isContractDateInferred":true}]}

Stream a Service Inventory Report

This endpoint reports on service inventory, and typically advises about the status of the inventory in one of many reporting modes. The modes of operation cater to reporting now or last month for a particular TFF RSP customer, to assist with periodically reconciling records in an automated fashion.

The API uses Server Sent Events (SSE) to stream the results to clients. SSE is a simple technique which the client opens a socket, and TFF delivers line-delimited JSON results to that socket as they are ready. The server will close the socket when there is no more data to consume. SSE enables the results to be collected as they are ready and a reference standard, instead of blocking for a longer period of time and/or implementing a custom paging mechanism.

Authorizations:
OAuth
query Parameters
mode
required
any
Enum: "active-now" "active-last-month"

Determines the mode of operation for this reporting endpoint.

  • active-now: Service inventory items that are active now; if customer data is changing this will update live. Useful for reporting on a reasonable defintion of now [1]

  • active-last-month: Service inventory items that were active in the last month; that is: data constrained to the last calendar month. Useful for reporting on a monthly basis.

    This is semi-stable i.e. successive calls should expect to return the same data until the definition of last month changes (e.g. a transition from March to April.)

[1]: There are some uncontrollable caching factors that may influence this. We make no guarantees about how often the cache is refreshed. Please consult with API product owner if you have special API needs relating to this.

customerId
any

Enables control of the customer ID to query for in a multi-customer token. If the token only has a single customer ID associated to it, then the API will use that.

Responses

Response samples

Content type
text/event-stream
{"customerId":1,"inventory":[{"id": "UFFXXXHM0653114","remoteId": "UFFXXXHM0653114","type": "UNI","port": "1","taggingMode": "tagged","circuitInsertion": "pppoe_ia","igPiid": "IDA100000001","svlan": "2","cvlan": "4","cevlan": "10"}]}
{"customerId":1,"inventory":[{"id": "UFFXXXHM0653114-0-ATA","remoteId": "UFFXXXHM0653114-0-ATA","type": "ATA","port": "1","cvlan": "3","svlan": "4","cevlan": "13","circuitInsertion": "DHCP Option 82","igPiid": "IDA100000001"}]}

Files

Stream an Address File

This endpoint serves up the marketing material address file.

Authorizations:
OAuth

Responses

Response samples

Content type
text/csv
OBJECTID,SUBURB,DISTRICT,REGION,ISLAND,PARCEL_ID,UFF_TYPE,UFF_AREA,PHYSICAL_ADDRESS,ADDRESS_STREET_NO,ADDRESS_STREET_NAME,ADDRESS_STREET_TYPE,ADDRESS_STREET_SUFFIX,IN_USE_TYPE,BUILD_DATE,RFS_DATE_PREM,UFF_CAID,RFS_DATE_ALL,STATE,X,Y,TUI,UNIQUEID,HABIT_NAME,MDU_SDU,ADDRESS_CLASSIFICATION,R_O_W,UNDERGROUND,LAYER2_STATUS,LAYER1_STATUS,MARKET_SEGMENT,FIBRE_ACCESS_CATEGORY,ZONE_TYPE,LAYER2_TECHNOLOGY,DPID,INPUT_SERVICE_STATUS,HYPERFIBRE_AVAILABLE,LEVEL_NO,LEVEL_TYPE,UNIT_TYPE,PROMOTION,place_id,is_primary,tag_value
1,SILVERDALE,HAMILTON CITY,Waikato Region,North Island,4376402,Primary,HME,3/78 CARRINGTON AVENUE,3/78,CARRINGTON AVENUE,AVENUE,,Yes (Developed),Mar-13,31/03/2013,HE_95669,31/03/2013,Service Ready,,,1007957369,0036250600HE974,,MDU_E,Multi Medium,NO,0,1,Intact ONU,Residential,Other,UFB1,GPON,,1,Yes,,,,,40256177UFFL80D,t,