This documentation is for the v2 (stable) version of the API.
Invocation URL: /v2/dynamiclabels/allocatewithaddress

Descripton:

Allocate (or quote) some label numbers from Fastway, based on Pickup/Delivery location and weight.
In the case of multiple labels (eg a Local service), an array of matching labels will be returned, and it is up to the caller to select the one they want to use. This method is designed to be called twice, firstly without the LabelColour parameter to get the list of options, and then with the LabelColour parameter (matching an option from the first call) to actually allocate the label.

Parameters:

PickupAddr1(required) - The Pickup address line 1 (eg, '123 test street')
PickupPostcode(required) - The Pickup Postcode (eg, '4137')
PickupTown(required) - The Pickup Town (eg, 'Napier')
DeliveryAddr1(required) - The Delivery address line 1 (eg, '123 test street')
DeliveryPostcode(required) - The Delivery Postcode (eg '2000')
DeliveryTown(required) - The Delivery Town (eg, 'Auckland')
DeliveryContactPhone - The delivery phone number
WeightInKg(required) - The weight of the parcel in kg (eg, '14')
CountryCode(required) - The CountryCode that the pickup/delivery addresses reside in (see main docs page)
LabelColour - If specified, will allocate a label based on the set colour. If the set colour is invalid for the pickup/delivery details specified, an error will be returned.
ClientIdentifier - If specified, will return the same label numbers between requests (if the ClientIdentifier is the same). This is to prevent loss of label numbers due to connection errors.
TestMode - 'true' or 'false'. If omitted, defaults to false. If set to true, will not allocate any labels, but will still return label numbers. These label numbers will be 'XXXXXXXXXXXX' and should only be used for testing purposes. Note that LabelColour should be set or there is no point in setting this.
PickupAddr2 - The Pickup address line 2 (eg, 'Unit 52') *Optional
DeliveryAddr2 - The Delivery address line 2 (eg, 'Unit 52') *Optional
Quantity - number of labels required (default 1), multi-label pricing will be taken into consideration.

Returns:

A data structure. In JSON, it looks like:

{
    'result': {
        'isRural': false,
		'isSaturdayDeliveryAvailable': true,
		'pickup_rf': 'NPE',
		'pickup_cf': '065',
		'delivery_rf': 'NPE',
		'delivery_cf': '060',	
		'pickup_location': 'Napier 4137',
		'delivery_location': 'Napier 4110',
		'delivery_timeframe_days': '1',
		'usable_labels': [
            {
                'base_label_colour': 'BROWN',
                'excess_label_count': 0,
                'base_label_cost_exgst': '2.00',
                'excess_label_cost_exgst': '0.00',
                'type':parcel'
            },
            {
                'base_label_colour': 'DKBLUE',
                'excess_label_count': 0,
                'base_label_cost_exgst': '4.00',
                'excess_label_cost_exgst': '0.00',
                'type':parcel'
            },
            {
                'base_label_colour': 'SAT-NAT-A4',
                'excess_label_count': 0,
                'base_label_cost_exgst': '6.00',
                'excess_label_cost_exgst': '0.00',
                'type':satchel'
            }
        ]
    },
    'generated_in': '375ms'
}
After choosing a label colour from the first call, the output of the second call could look like:
{
    'result': {
        'pickup_rf': 'NPE',
        'delivery_rf': 'NPE',
        'pickup_location': 'Napier 4112',
        'delivery_location': 'Napier 0',
        'delivery_timeframe_days': '1',
        'usable_labels': [
            {
                'base_label_colour': 'BROWN',
                'excess_label_count': 0,
                'base_label_cost_exgst': '2.00',
                'base_label_number': 'BW0000652466',
                'excess_label_cost_exgst': 0,
				'excess_label_numbers' : []
            }
        ]
    },
    'generated_in': '156ms'
}

Example:

Show what labels are available when sending from Napier 4137 to Napier 4137:
https://api.fastway.org/v2/dynamiclabels/allocatewithaddress/123%20Test%20street/4137/Napier/456%20Test%20street/4137/Napier/12/6?api_key=YOUR_API_KEY
Allocate a BROWN label for sending between Napier 4137 and Napier 4137:
https://api.fastway.org/v2/dynamiclabels/allocatewithaddress/123%20Test%20street/4137/Napier/456%20Test%20street/4137/Napier/12/6/Brown?api_key=YOUR_API_KEY

Back to Dynamic Labels