Technical Documentation

Read our Release Notes here.

In this technical documentation:

Open API Specification

View the Customer Integration Open API 3.0 Specification >

Getting Connected

Access to the API is authorized using OAuth 2.0 client credentials flow which allows a client to authenticate with the authorisation server using a client_id and client_secret. Once authenticated the client is issued with a token it can use to make authorized requests to the customer integration API.

Postman Examples for the Sandbox

The Freightways Customer Integration Api Postman Workspace has example requests for each of the different endpoints in the api.  You can use this as a quick start to exploring our API in the Sandbox, which is an area where you can safely experiment with our API.

Postman Variables:








Url of customer integration api


Authentication url








Account Carrier

NZCouriers, PostHaste, CastleParcels, NowCouriers


Account Customer Id




To use the API either in code or with another tool you will need the following URLs.

These URLs are for the Sandbox, please enquire for the production endpoints after completion of development and testing in the sandbox.







Customer Integration

This is the base URL that you will use to access the customer integration endpoints as defined in the swagger spec.


The oauth endpoint you use to exchange your clientid and secret for a JWT token.


NOTE: Please ensure that only a single / is used in the url, you may get htpp 404 Not Found errors if you use a url such as So when configuring postman please do not add a trailing / to the baseUrlCI variable.


Code Snippets

Obtaining an Access Token

The following C# code snippet demonstrates making a call to the authorization server to obtain an access token. Replace #{CLIENT_ID_HERE}#, #{CLIENT_SECRET_HERE}# and #{OAUTH2_TOKEN_URL_HERE}# with your supplied values

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 var httpClient = new HttpClient(); // Create request httpClient.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json")); string credentials = String.Format("{0}:{1}", "#{CLIENT_ID_HERE}#", "#{CLIENT_SECRET_HERE}#"); httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials))); var values = new Dictionary<string, string> { { "grant_type", "client_credentials" } }; var content = new FormUrlEncodedContent(values); var response = await httpClient.PostAsync("#{OAUTH2_TOKEN_URL_HERE}#", content); // Issue the request var result = await response.Content.ReadAsStringAsync(); dynamic tokenDetails = JObject.Parse(result); // Retrieve the token that can be used to make requests of the API string accessToken = tokenDetails.access_token;


Calling the API

Once a valid token has been obtained requests can be made to the API including the token in the header.

1 2 3 4 5 6 7 8 9 10 11 12 var httpClient = new HttpClient(); // Add the Access Token to the request httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken); string requestJson= "#{REQUEST_BODY_AS_JSON_HERE}#"; var content = new StringContent(requestJson, Encoding.UTF8, "application/json"); var response = await httpClient.PostAsync("#{CUSTOMER_INTEGRATION_URL_HERE}#", content); // If you need to discuss a call with Freightways support the returned correlationId will enable us to identify the call in our logs var correlationId = response.Headers.GetValues("X-Correlation-ID").FirstOrDefault();

Selecting Carrier and Customer

When using the Customer Integration API the Carrier and Customer ID are provided as part of the URL. e.g. /v1/carriers/NZCouriers/customers/12345678/rates.

Valid Carriers are:

  • NZCouriers

  • PostHaste

  • CastleParcels

  • NowCouriers

The Customer ID is validated against the access token to ensure the correct account is accessed.

Date and Time Handling

All dates in the request and response payloads are UTC times and the standard ISO 8601 formatting is used. e.g. 2020-08-12T20:17:46.384Z


Detail on how to map AddressRight fields to the Freightways address object.

Street = addressRightAddress.FormattedAddress.Line1
Secondary = addressRightAddress.FormattedAddress.Line2
Suburb = addressRightAddress.StructuredAddress.Suburb
Town = addressRightAddress.StructuredAddress.Town
PostCode = addressRightAddress.StructuredAddress.Postcode
Country = addressRightAddress.StructuredAddress.Country
AddressValidationSource = "AddressRight"
AddressValidationId = addressRightAddress.References.Id

Sequence Diagrams

Customer Integration, devdocs, sequence, flow

Example Scenarios

Validating an address and determining the geo-coordinates of the address is performed using the AddressRight functionality we have integrated into the API via the following endpoints.

  • /v1/addressFuzzy

  • /v1/addressMatch

  • /v1/addressAutocomplete

Once you have a verified address you can exchange the ID for a full address object which can be used for rating, consignments, and pickup requests using

  • /v1/addresses/{addressId}

If you do not have a validated address then you can still request rates and create consignments by providing an address with a valid suburb, town, and optional postcode.

The charges for the consignment will be indicative only of the specific address and hence available services will be unknown, further costs may be applied.

If we are unable to accurately identify the address a warning is returned within the response payload from the rating and consignment requests.

This consignment was created without a validated lat/lon. The costs were based on a proximity location. Further charges and a differing service level may apply based on the actual delivery address.

If you requested Saturday delivery and the address is unvalidated then the Saturday delivery option is ignored. If the Saturday delivery option has been selected, it will be shown in the responses' isSaturdayDelivery flag.

Once a geo-coordinate has been obtained the services available to the address can be retrieved from the services endpoint /v1/services.

The geo-coordinate can also be used to retrieve the service locations in proximity using /v1/service-locations.

This endpoint allows filtering by the type of Service Location and specifying a radius from the geo-coordinate. If no radius is provided it will return all service locations.

With a valid geo-coordinate for the address the rate for a consignment can be determined using /v1/carriers/{carrierName}/customers/{customerId}/rates.

A consignment can be created with a POST to /v1/carriers/{carrierName}/customers/{customerId}/consignments.

The response will include the identifiers for each item, barcode strings for each consignment item, and the calculated cost.

This request can also be used to create a label in which case the response will include a link to retrieve the barcode.

A request to cancel a consignment can be made with a POST to /v1/carriers/{carrierName}/customers/{customerId}/consignments/{consignmentId}/CancellationRequests

At this time, this will record a request to cancel which will be manually handled.

A consignment can be created with a POST to /v1/carriers/{carrierName}/customers/{customerId}/pickup-location-pickup-requests

This post will identify the pickup location using the issued PIN identifier.

If a label needs to be reprinted for an existing consignment place a GET request to /v1/carriers/{carrierName}/customers/{customerId}/consignments/{consignmentId}/labels