API docs by Redocly

Coural API (v12.1.0 - Little Cuckoo)

Download OpenAPI specification:

Ping

Health check endpoint.

Ping

Health check endpoint. Returns the application name from the request path.

Responses

Response samples

Content type
application/json
"portal"

BCTI

Endpoints for managing Buyer Created Tax Invoices (BCTIs).

List BCTIs

Lists all BCTI PDF files for a given year and month. Returns pre-signed S3 download URLs.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Combined BCTIs

Gets the pre-merged combined PDF for a distributor's BCTIs for a given month. Returns a download link if the combined file exists.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "fileName": "string",
  • "hyperlink": "string",
  • "contractor": -1,
  • "contractorName": "[NO CONTRACTOR]",
  • "distributor": -1,
  • "distributorName": "[NO DISTRIBUTOR]",
  • "invoicePeriod": "01/2024",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "isAccounts": true
}

Combine BCTIs

Triggers the merging of individual BCTI PDFs into a single combined PDF for the specified distributor and month.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "message": "Combining 5 files"
}

Get Combined BCTIs (Accounts)

Gets the pre-merged combined PDF for a distributor's "accounts" BCTIs for a given month.

"Accounts" BCTIs are for contractors with either no configured email address, or with the email address set to accounts@coural.co.nz.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "fileName": "string",
  • "hyperlink": "string",
  • "contractor": -1,
  • "contractorName": "[NO CONTRACTOR]",
  • "distributor": -1,
  • "distributorName": "[NO DISTRIBUTOR]",
  • "invoicePeriod": "01/2024",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "isAccounts": true
}

Combine BCTIs (Accounts)

Triggers the merging of individual "accounts" BCTI PDFs into a single combined PDF for the specified distributor and month.

"Accounts" BCTIs are for contractors with either no configured email address, or with the email address set to accounts@coural.co.nz.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "message": "Combining 5 files"
}

Get Zipped BCTIs

Generates and returns a ZIP archive containing all individual BCTI PDFs for the specified distributor and month.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "fileName": "string",
  • "hyperlink": "string",
  • "contractor": -1,
  • "contractorName": "[NO CONTRACTOR]",
  • "distributor": -1,
  • "distributorName": "[NO DISTRIBUTOR]",
  • "invoicePeriod": "01/2024",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "isAccounts": true
}

Get Zipped BCTIs (Accounts)

Generates and returns a ZIP archive containing all individual "accounts" BCTI PDFs for the specified distributor and month.

"Accounts" BCTIs are for contractors with either no configured email address, or with the email address set to accounts@coural.co.nz.

path Parameters
{year}
required
integer
Example: 2024
{month}
required
integer
Example: 1
{distributor}
required
integer
Example: 1

Contractor ID of the distributor.

Responses

Response samples

Content type
application/json
{
  • "fileName": "string",
  • "hyperlink": "string",
  • "contractor": -1,
  • "contractorName": "[NO CONTRACTOR]",
  • "distributor": -1,
  • "distributorName": "[NO DISTRIBUTOR]",
  • "invoicePeriod": "01/2024",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "isAccounts": true
}

BCTI - Rates

Endpoints for managing contractor rates used in BCTI generation.

List Rates

Lists all contractor rates, ordered by ScanType, TicketType, Role, Courier, OversizeTickets, DateFromNZST, ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Rate

Creates a new contractor rate record.

Request Body schema: application/json
required
scanType
integer
Enum: 0 1 2 3 4 5 6

The scan type. Values correspond to Pickup, PickupOutForDelivery, Delivery, OutForDeliveryOnly, Error, StorePickup, and StoreDelivery respectively.

ticketType
integer
Enum: 0 1 2 3 4 5

The ticket type. Values correspond to Parcel, Document, Signature, Excess, Foodbox, and R18 respectively.

role
string
Default: ""
courier
integer or null
Default: null

Optional courier ID to restrict this rate to a specific courier.

oversizeTickets
integer or null
Default: null

Optional oversize ticket threshold.

dateFrom
string or null <date-time>
Default: null

Start of the rate's effective period (NZST).

dateTo
string or null <date-time>
Default: null

End of the rate's effective period (NZST).

rate
number or null
Default: null

The dollar rate value.

Responses

Request samples

Content type
application/json
{
  • "scanType": 0,
  • "ticketType": 0,
  • "role": "",
  • "courier": null,
  • "oversizeTickets": null,
  • "dateFrom": null,
  • "dateTo": null,
  • "rate": null
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "scanType": 0,
  • "ticketType": 0,
  • "role": "",
  • "courier": null,
  • "oversizeTickets": null,
  • "dateFrom": null,
  • "dateTo": null,
  • "rate": null
}

Update Rate

Updates an existing contractor rate record.

path Parameters
{id}
required
integer
Example: 1
Request Body schema: application/json
required
scanType
integer
Enum: 0 1 2 3 4 5 6

The scan type. Values correspond to Pickup, PickupOutForDelivery, Delivery, OutForDeliveryOnly, Error, StorePickup, and StoreDelivery respectively.

ticketType
integer
Enum: 0 1 2 3 4 5

The ticket type. Values correspond to Parcel, Document, Signature, Excess, Foodbox, and R18 respectively.

role
string
Default: ""
courier
integer or null
Default: null

Optional courier ID to restrict this rate to a specific courier.

oversizeTickets
integer or null
Default: null

Optional oversize ticket threshold.

dateFrom
string or null <date-time>
Default: null

Start of the rate's effective period (NZST).

dateTo
string or null <date-time>
Default: null

End of the rate's effective period (NZST).

rate
number or null
Default: null

The dollar rate value.

Responses

Request samples

Content type
application/json
{
  • "scanType": 0,
  • "ticketType": 0,
  • "role": "",
  • "courier": null,
  • "oversizeTickets": null,
  • "dateFrom": null,
  • "dateTo": null,
  • "rate": null
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "scanType": 0,
  • "ticketType": 0,
  • "role": "",
  • "courier": null,
  • "oversizeTickets": null,
  • "dateFrom": null,
  • "dateTo": null,
  • "rate": null
}

Delete Rate

Deletes a contractor rate record by ID.

path Parameters
{id}
required
integer
Example: 1

Responses

Contractor

Endpoints for contractor management.

Create Contractor

Creates a new contractor record.

Automatically adds workflow tags for WelcomeEmailNotSent and ContractorAgreementNotCompleted.

Request Body schema: application/json
required
name
string
Default: ""
status
integer
Default: 0
Enum: 0 1

Values correspond to Active and Archived respectively.

isShareHolder
boolean
Default: false
sharesNotes
string
Default: ""
started
string <date-time>
left
string <date-time>
bankAccount
string
Default: ""
gstNumber
string
Default: ""
hasGST
boolean
Default: false
podNotes
string
Default: ""
isDistributor
boolean
Default: false
isSubDistributor
boolean
Default: false
subDistRate
number
Default: 1

Sub-distributor rate reduction factor.

isContractor
boolean
Default: false
isStore
boolean
Default: false
sendJobDetails
boolean
Default: false
sendDeliveryAdvice
boolean
Default: false
isCurrent
boolean
Default: false
isDropoff
boolean
Default: false
isPallet
boolean
Default: false
isPH
boolean
Default: false
splitBCTIByRoute
boolean
Default: false
isDeliveryScanCompliant
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "",
  • "status": 0,
  • "isShareHolder": false,
  • "sharesNotes": "",
  • "started": "2019-08-24T14:15:22Z",
  • "left": "2019-08-24T14:15:22Z",
  • "bankAccount": "",
  • "gstNumber": "",
  • "hasGST": false,
  • "podNotes": "",
  • "isDistributor": false,
  • "isSubDistributor": false,
  • "subDistRate": 1,
  • "isContractor": false,
  • "isStore": false,
  • "sendJobDetails": false,
  • "sendDeliveryAdvice": false,
  • "isCurrent": false,
  • "isDropoff": false,
  • "isPallet": false,
  • "isPH": false,
  • "splitBCTIByRoute": false,
  • "isDeliveryScanCompliant": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "",
  • "status": 0,
  • "isShareHolder": false,
  • "sharesNotes": "",
  • "started": "2019-08-24T14:15:22Z",
  • "left": "2019-08-24T14:15:22Z",
  • "bankAccount": "",
  • "gstNumber": "",
  • "hasGST": false,
  • "podNotes": "",
  • "isDistributor": false,
  • "isSubDistributor": false,
  • "subDistRate": 1,
  • "isContractor": false,
  • "isStore": false,
  • "sendJobDetails": false,
  • "sendDeliveryAdvice": false,
  • "isCurrent": false,
  • "isDropoff": false,
  • "isPallet": false,
  • "isPH": false,
  • "splitBCTIByRoute": false,
  • "isDeliveryScanCompliant": false,
  • "contactNames": [
    ],
  • "contacts": [
    ],
  • "addresses": [
    ]
}

Get Contractor BCTIs

Lists all BCTI PDF files for a specific contractor across all invoice periods. Returns pre-signed S3 download URLs.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Contractor - Workflow

Endpoints for managing contractor onboarding workflow, including document submissions and status tags.

Get Workflow Documents

Gets the list of available workflow documents and forms with pre-signed S3 download URLs.

The contractor ID in the path is not used for filtering — all documents are returned regardless of contractor.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

Responses

Response samples

Content type
application/json
{
  • "documents": [
    ],
  • "forms": [
    ]
}

Get Workflow Tags

Gets all workflow tags and document tags for the specified contractor. Document tags include pre-signed download URLs.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ],
  • "documentTags": [
    ]
}

Add Workflow Tags

Adds workflow tags and/or document tags to the specified contractor.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

Request Body schema: application/json
required
Array of objects (Workflow Tag - Input)
Array of objects (Workflow Document Tag - Input)

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ],
  • "documentTags": [
    ]
}

Response samples

Content type
application/json
{
  • "tags": [
    ],
  • "documentTags": [
    ]
}

Delete Workflow Tags

Deletes workflow tags by ID for the specified contractor. Only tags belonging to the specified contractor will be removed.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

Request Body schema: application/json
required
Array
integer

Responses

Request samples

Content type
application/json
[
  • 1,
  • 2,
  • 3
]

Submit Workflow File

Submits a document file for the specified contractor. The file is uploaded to S3 and a document tag with PendingApproval status is created.

The file must be Base64-encoded in the request body.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

{document_type}
required
string
Enum: "ContractorAgreement" "SharesSurrenderAndApplication" "SharesTransfer"
Example: ContractorAgreement

Must be a document tag type name.

Request Body schema: application/json
required
filename
string
file
string <byte>

Base64-encoded file content.

Responses

Request samples

Content type
application/json
{
  • "filename": "agreement.pdf",
  • "file": "string"
}

Response samples

Content type
application/json
"agreement.pdf"

Set Document Status

Updates the document status of a specific workflow document tag.

path Parameters
{contractor}
required
integer
Example: 1

Contractor ID.

{tag_id}
required
integer
Example: 1
{status}
required
integer
Enum: 0 1 2 3 4
Example: 1

Values correspond to PendingApproval, Completed, Denied, Withdrawn, and PendingPayment respectively.

Responses

Response samples

Content type
application/json
{
  • "tagId": 0,
  • "status": 0
}

Courier

Endpoints for courier management.

Create Courier

Creates a new courier record. Rates can optionally be included in the request body.

Request Body schema: application/json
required
name
string
Default: ""
email
string
Default: ""
sendEmail
boolean
Default: false
scanCode
string
Default: ""
trackingSiteLink
string
Default: ""
status
integer
Default: 0
Enum: 0 1 2

Values correspond to Active, Archived, and OnHold respectively.

Array of objects or null (Courier Rate - Input)

Optional. If provided, rates will be saved with the courier.

Responses

Request samples

Content type
application/json
{
  • "name": "",
  • "email": "",
  • "sendEmail": false,
  • "scanCode": "",
  • "trackingSiteLink": "",
  • "status": 0,
  • "rates": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "",
  • "email": "",
  • "sendEmail": false,
  • "scanCode": "",
  • "trackingSiteLink": "",
  • "status": 0,
  • "rates": [
    ]
}

Get Courier

Gets a courier by ID, including their rates.

path Parameters
{courier}
required
integer
Example: 1

Courier ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "",
  • "email": "",
  • "sendEmail": false,
  • "scanCode": "",
  • "trackingSiteLink": "",
  • "status": 0,
  • "rates": [
    ]
}

Update Courier

Updates a courier record. If rates are included, they will be saved (new rates inserted, existing rates updated, missing rates deleted).

path Parameters
{courier}
required
integer
Example: 1

Courier ID.

Request Body schema: application/json
required
name
string
Default: ""
email
string
Default: ""
sendEmail
boolean
Default: false
scanCode
string
Default: ""
trackingSiteLink
string
Default: ""
status
integer
Default: 0
Enum: 0 1 2

Values correspond to Active, Archived, and OnHold respectively.

Array of objects or null (Courier Rate - Input)

Optional. If provided, rates will be saved with the courier.

Responses

Request samples

Content type
application/json
{
  • "name": "",
  • "email": "",
  • "sendEmail": false,
  • "scanCode": "",
  • "trackingSiteLink": "",
  • "status": 0,
  • "rates": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "",
  • "email": "",
  • "sendEmail": false,
  • "scanCode": "",
  • "trackingSiteLink": "",
  • "status": 0,
  • "rates": [
    ]
}

Query Couriers

Queries couriers with optional filtering and pagination.

String filters use SQL LIKE syntax. Null values apply no filter.

Request Body schema: application/json
required
nameLike
string or null
Default: null

SQL LIKE filter on courier name.

scanCodeLike
string or null
Default: null

SQL LIKE filter on scan code.

statusIn
Array of integers or null
Default: null
Enum: 0 1 2

Filter by courier status. Values correspond to Active (0), Archived (1), and OnHold (2).

page
integer or null
Default: null
limit
integer or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "nameLike": null,
  • "scanCodeLike": null,
  • "statusIn": null,
  • "page": null,
  • "limit": null
}

Response samples

Content type
application/json
[
  • {
    }
]

Courier - Invoices

Endpoints for courier invoice generation, querying, and lock date management.

Get Invoices

Gets courier invoices with optional filtering. Returns pre-signed S3 download URLs for invoice PDFs.

query Parameters
isBilled
boolean

Filter by billed status.

includeTickets
boolean

Include the list of billed ticket numbers in the response.

startDate
string <date-time>

Filter invoices with date range starting on or after this date.

endDate
string <date-time>

Filter invoices with date range ending on or before this date.

courier
integer

Filter by courier ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Query Invoices

Queries courier invoices with filtering and pagination.

All filter parameters are optional. Null values apply no filter. page and limit can also be passed as query string parameters.

query Parameters
page
integer

Overrides page in request body.

limit
integer

Overrides limit in request body.

Request Body schema: application/json
required
idIn
Array of integers or null
Default: null
courierIn
Array of integers or null
Default: null
billedToLike
string or null
Default: null

SQL LIKE filter on courier name.

dateRangeStartAfter
string or null <date-time>
Default: null
dateRangeStartBefore
string or null <date-time>
Default: null
dateRangeEndAfter
string or null <date-time>
Default: null
dateRangeEndBefore
string or null <date-time>
Default: null
billedOnAfter
string or null <date-time>
Default: null
billedOnBefore
string or null <date-time>
Default: null
billedOnIsNull
boolean or null
Default: null

Filter by whether the invoice has been billed.

orderby
string or null
Default: null

A SQL order by clause. Valid columns: ID, Courier, BilledTo, BilledOn, DateRangeStart, InvoiceDateStart, InvoiceDateRangeStart, DateRangeEnd, InvoiceDateEnd, InvoiceDateRangeEnd.

page
integer
Default: 0
limit
integer
Default: 20

Responses

Request samples

Content type
application/json
{
  • "idIn": null,
  • "courierIn": null,
  • "billedToLike": null,
  • "dateRangeStartAfter": null,
  • "dateRangeStartBefore": null,
  • "dateRangeEndAfter": null,
  • "dateRangeEndBefore": null,
  • "billedOnAfter": null,
  • "billedOnBefore": null,
  • "billedOnIsNull": null,
  • "orderby": null,
  • "page": 0,
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 0
}

Generate Invoice

Generates courier invoices for the specified date range.

If sendToXero is true, invoices are also sent to Xero and emailed to couriers with configured email addresses. Both startDate and endDate are required.

Request Body schema: application/json
required
startDate
required
string <date-time>

Start of the invoice period.

endDate
required
string <date-time>

End of the invoice period.

couriers
Array of integers
Default: []

Optional list of courier IDs to generate for. Empty array generates for all couriers.

sendToXero
boolean
Default: false

If true, sends invoices to Xero and emails them to couriers.

Responses

Request samples

Content type
application/json
{
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "couriers": [ ],
  • "sendToXero": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Lock Date

Gets the current courier invoice lock date. Tickets scanned before this date cannot be included in new invoices.

Responses

Response samples

Content type
application/json
"2019-08-24T14:15:22Z"

Set Lock Date

Sets the courier invoice lock date.

path Parameters
{date}
required
string <date>
Example: 2024-01-31

Responses

Response samples

Content type
text/plain
Lock Date: 31/01/2024 12:00:00 AM

Route

Endpoints for route management and GeoJSON data.

Query Routes

Queries routes by a list of IDs.

If list is null or undefined, returns 400 Bad Request — only query-by-list is currently supported.

page and limit can be provided in the request body or overridden via query string parameters.

Set loadBoxNumbers to true to include box number counts in the response. Defaults to false.

query Parameters
page
integer

Overrides page in request body.

limit
integer

Overrides limit in request body.

Request Body schema: application/json
required
list
Array of integers

List of route IDs to retrieve.

page
integer or null
Default: null
limit
integer or null
Default: null
loadBoxNumbers
boolean
Default: false

When true, includes box number counts in each route's boxNumbers field.

Responses

Request samples

Content type
application/json
{
  • "list": [
    ],
  • "page": null,
  • "limit": null,
  • "loadBoxNumbers": false
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "maxAvailableItems": 0
}

Get Route

Gets one or more routes by ID. Supports comma-separated IDs for batch retrieval.

If a single ID is provided, returns a single route object. If multiple IDs are provided, returns an array.

path Parameters
{route}
required
string
Example: 1

Route ID. Supports comma-separated IDs for batch retrieval.

query Parameters
box_numbers
boolean

Include box number counts in the response.

Responses

Response samples

Content type
{
  • "route_id": 0,
  • "status": 0,
  • "depot": 1,
  • "island": "",
  • "noTicketHeader": false,
  • "isHidden": false,
  • "region": "",
  • "area": "",
  • "code": "",
  • "description": "",
  • "pmpAreacode": 0,
  • "pmpRuncode": 0,
  • "ovatoRD": 0,
  • "seqRegion": 0,
  • "seqArea": 0,
  • "seqCode": 0,
  • "boxNumbers": {
    }
}

Update Route

Updates a route record. If boxNumbers is provided, new box number records will be inserted where they differ from the current active values.

path Parameters
{route}
required
string
Example: 1

Route ID. Supports comma-separated IDs for batch retrieval.

Request Body schema: application/json
required
status
integer
Default: 0
Enum: 0 1

Values correspond to Active and Archived respectively.

depot
integer
Default: 1
island
string
Default: ""
noTicketHeader
boolean
Default: false
isHidden
boolean
Default: false
region
string
Default: ""
area
string
Default: ""
code
string
Default: ""
description
string
Default: ""
pmpAreacode
integer
Default: 0
pmpRuncode
integer
Default: 0
ovatoRD
integer
Default: 0
seqRegion
integer
Default: 0
seqArea
integer
Default: 0
seqCode
integer
Default: 0
boxNumbers
object or null

Key-value pairs of box type code to count.

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "depot": 1,
  • "island": "",
  • "noTicketHeader": false,
  • "isHidden": false,
  • "region": "",
  • "area": "",
  • "code": "",
  • "description": "",
  • "pmpAreacode": 0,
  • "pmpRuncode": 0,
  • "ovatoRD": 0,
  • "seqRegion": 0,
  • "seqArea": 0,
  • "seqCode": 0,
  • "boxNumbers": {
    }
}

Create Route

Creates a new route record. If boxNumbers is provided, initial box number records will be created.

Request Body schema: application/json
required
status
integer
Default: 0
Enum: 0 1

Values correspond to Active and Archived respectively.

depot
integer
Default: 1
island
string
Default: ""
noTicketHeader
boolean
Default: false
isHidden
boolean
Default: false
region
string
Default: ""
area
string
Default: ""
code
string
Default: ""
description
string
Default: ""
pmpAreacode
integer
Default: 0
pmpRuncode
integer
Default: 0
ovatoRD
integer
Default: 0
seqRegion
integer
Default: 0
seqArea
integer
Default: 0
seqCode
integer
Default: 0
boxNumbers
object or null

Key-value pairs of box type code to count.

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "depot": 1,
  • "island": "",
  • "noTicketHeader": false,
  • "isHidden": false,
  • "region": "",
  • "area": "",
  • "code": "",
  • "description": "",
  • "pmpAreacode": 0,
  • "pmpRuncode": 0,
  • "ovatoRD": 0,
  • "seqRegion": 0,
  • "seqArea": 0,
  • "seqCode": 0,
  • "boxNumbers": {
    }
}

Response samples

Content type
application/json
{
  • "route_id": 0,
  • "status": 0,
  • "depot": 1,
  • "island": "",
  • "noTicketHeader": false,
  • "isHidden": false,
  • "region": "",
  • "area": "",
  • "code": "",
  • "description": "",
  • "pmpAreacode": 0,
  • "pmpRuncode": 0,
  • "ovatoRD": 0,
  • "seqRegion": 0,
  • "seqArea": 0,
  • "seqCode": 0,
  • "boxNumbers": {
    }
}

Get Box Number Definitions

Gets all box number type definitions, ordered by index.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get GeoJSON

Gets GeoJSON feature data for routes. Exactly one of the following query parameters must be provided:

  • route — Comma-separated route IDs
  • job_id — Job ID (loads routes associated with the job)
  • region — Comma-separated region names

When using job_id, an optional override_box_type parameter can be provided to override box number counts with job route amounts for the specified box type.

Each feature includes a geometry_url property containing a pre-signed S3 URL to the full-detail route geometry file (8% simplification), and a geometry_url_simple property containing a pre-signed S3 URL to the simplified geometry file (1% simplification) for faster initial map load.

query Parameters
route
string
Example: route=1,2,3

Comma-separated route IDs.

job_id
integer

Job ID to load routes from.

region
string
Example: region=Auckland

Comma-separated region names.

override_box_type
string
Example: override_box_type=CP

Box type code to override with job route amounts. Only used with job_id.

Responses

Response samples

Content type
[
  • {
    }
]

Job

Endpoints for job creation.

Create Jobs from DX Mail

Creates jobs from a DX Mail CSV file. The request body must be raw CSV text.

The CSV must contain either a Route ID or Postcode column as the route identifier. Additional columns matching configured DX Mail job template names will generate jobs.

DX mail templates are defined by records with keys like 'DX Mail Job Template - %' in the Misc table. These map a column name (the % in the key) to jobs to use as templates. These jobs typically have negative ID numbers.

An optional Version column can be included. This is passed into the Version field on job-route affiliations.

Request Body schema: text/csv
required
string

Raw CSV content with route identifiers and job amount columns.

Responses

Request samples

Content type
text/csv
Route ID,Version,Magazine Direct,Large Oversize Direct
1,A,100,50
2,A,200,75

Response samples

Content type
application/json
{
  • "Magazine Direct": {
    },
  • "Large Oversize Direct": {
    }
}

POD

Endpoints for Proof of Delivery action management.

Get POD Actions

Gets all actions for a POD record, ordered by most recent first. Actions are stored in DynamoDB.

path Parameters
{pod}
required
integer
Example: 1

POD ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update POD Action

Creates or updates a POD action. Updates both the DynamoDB action record and the POD's last action fields in MySQL.

path Parameters
{pod}
required
integer
Example: 1

POD ID.

Request Body schema: application/json
required
timestamp
string <date-time>

Defaults to current UTC time.

actionType
integer
Enum: 0 1 2 3 4 5 6 16 17 18 19 20 21 22 25 26 27 28 29 30 31

Values include: NoAction (0), ContractorContacted (1), ContractorResponse (2), ContractorAdvisesHold (3), SignatureCopyRequested (4), CourierContacted (5), CourierResponse (6), FinalResponse (16), ContractorPhoneNoResponse (17), ContractorLeftMessage (18), Other (19), ContractorEmailSent (20), ContractorCheckTicket (21), CourierSeekingResponse (22), HoldForTicketSheets (25), HoldForMobileScans (26), MobileScanGPS (27), EmailOut (28), EmailIn (29), TextOut (30), TextIn (31).

object
notes
string
Default: ""
staff
string
Default: ""

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "actionType": 0,
  • "meta": {
    },
  • "notes": "",
  • "staff": ""
}

Response samples

Content type
application/json
{
  • "timestamp": "2019-08-24T14:15:22Z",
  • "actionType": 0,
  • "meta": {
    },
  • "notes": "",
  • "staff": ""
}

Message

Endpoints for sending emails and SMS via Kereru.

Send Email

Queues one or more emails for sending via the Kereru SQS queue. The tenancy is automatically set from the request context.

Uses the EmailPacket model from Firecrest.Kereru.Client.

Request Body schema: application/json
required
Array
code
string
Default: ""

Email template code.

object or null

Optional sender. Can be set at tenancy level.

Array of objects

Recipient email addresses. Accepts EmailAddress objects or plain strings via implicit conversion.

Array of objects
Default: []
Array of objects
Default: []
attachments
Array of strings
Default: []
subject
string
Default: ""
inReplyTo
string or null
Default: null
htmlMessage
string
Default: ""
plainTextMessage
string
Default: ""
batchID
string or null <uuid>

Optional client reference, not used by Kereru.

originID
string or null <uuid>

Optional client reference, not used by Kereru.

priority
integer
Default: 0
Enum: 0 1 2

Values correspond to Low, Medium, and High respectively.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Send SMS

Queues one or more SMS messages for sending via the Kereru SQS queue. The tenancy is automatically set from the request context.

Uses the SMSPacket model from Firecrest.Kereru.Client.

Request Body schema: application/json
required
Array
reference
string or null
Default: null
toSMS
Array of strings

Recipient phone numbers.

message
string
Default: ""
batchID
string or null <uuid>

Optional client reference, not used by Kereru.

originID
string or null <uuid>

Optional client reference, not used by Kereru.

priority
integer
Default: 0
Enum: 0 1 2

Values correspond to Low, Medium, and High respectively.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

System Journal

Endpoints for system journal entries.

Get Journal Entries

Gets all system journal entries, ordered by ID descending (most recent first).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Journal Entry

Creates a new system journal entry.

Request Body schema: application/json
required
logDate
string <date-time>
user
string
Default: ""
category
integer
Enum: 0 1 2 3

Values correspond to Exception, Job, Ticket, and General respectively.

startID
integer or null
Default: null
endID
integer or null
Default: null
remarks
string
Default: ""

Responses

Request samples

Content type
application/json
{
  • "logDate": "2019-08-24T14:15:22Z",
  • "user": "",
  • "category": 0,
  • "startID": null,
  • "endID": null,
  • "remarks": ""
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "logDate": "2019-08-24T14:15:22Z",
  • "user": "",
  • "category": 0,
  • "startID": null,
  • "endID": null,
  • "remarks": ""
}

Global Profile

Endpoints for global profile configuration.

Get Global Profile

Gets the global profile configuration.

Responses

Response samples

Content type
application/json
{
  • "gst": 0.15,
  • "deliveryScanPremiumRate": 0.1,
  • "fuelAdjustmentFactorRate": 0.05,
  • "ticketsPerBook": {
    }
}

Update Global Profile

Updates the global profile configuration. The request body is merged into the existing profile using JSON population.

Request Body schema: application/json
required
gst
number

GST rate as a decimal (e.g. 0.15 for 15%).

deliveryScanPremiumRate
number

Delivery Scan Premium rate used in BCTI calculations.

fuelAdjustmentFactorRate
number

Fuel Adjustment Factor rate used in BCTI calculations.

object

Map of ticket type name to tickets per book count.

Responses

Request samples

Content type
application/json
{
  • "gst": 0.15,
  • "deliveryScanPremiumRate": 0.1,
  • "fuelAdjustmentFactorRate": 0.05,
  • "ticketsPerBook": {
    }
}

Resource Tags

Endpoints for querying resource tags.

Query Resource Tags

Queries resource tags with a nested filter structure. Returns flat array results.

The filter is structured as { Type: { Resource: [Tag, ...] } }. Both Resource and Tag values support SQL LIKE wildcards (%).

Request Body schema: application/json
required
object

Nested filter: { Type: { Resource: [Tag, ...] } }

Responses

Request samples

Content type
application/json
{
  • "Ticket": {
    }
}

Response samples

Content type
application/json
[
  • [
    ]
]

Query Resource Tags (Nested)

Queries resource tags with the same filter as /tags/query, but returns results in a nested object structure: { Type: { Resource: { Tag: Value } } }.

Request Body schema: application/json
required
object

Nested filter: { Type: { Resource: [Tag, ...] } }

Responses

Request samples

Content type
application/json
{
  • "Ticket": {
    }
}

Response samples

Content type
application/json
{
  • "Ticket": {
    }
}

Ticket

Endpoints for ticket image and oversize ticket data.

Get Ticket Images

Gets pre-signed S3 download URLs for all images associated with a ticket.

path Parameters
{ticket}
required
string
Example: ABC123

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Oversize Tickets

Gets all oversize ticket numbers associated with a ticket.

path Parameters
{ticket}
required
string
Example: ABC123

Responses

Response samples

Content type
application/json
[
  • "string"
]