Below is all the information you need to use our API to request pricing for a booking across the metro areas of Sydney, Melbourne, Brisbane, Canberra, Adelaide, and Perth.

NOTE:

  • Interstate options are currently only available through the customer login portal here.
    We will return an error message for any attempted interstate deliveries, however as a developer it is advised that you handle these error messages accordingly.
  • Quotes can only be generated for one parcel at a time. For deliveries with multiple parcel types, please use the customer login portal here.
  • When creating runs, bookings will be pushed through into a holding table awaiting confirmation, allowing you to post bookings until you are ready to carry out the order.
    Once all consignment data has been sent, contact Zoom2u to confirm submission and have the runs created.
    Please notify Zoom2u up to 24 hours before a run is to be carried out so drivers can be arranged. Do note consignment data does not have to be sent 24 hours prior.

 

Request

Endpoint

MethodEndpointNotes
POSThttps://api.zoom2u.com/api/v1/delivery/createRequires delivery, pickup, and drop off information to be provided.

Request Headers

{
  "Authorization" : "Bearer your-token-goes-here",
  "Content-Type"  : "application/json"
}

You will need to retrieve the bearer token by logging into your customer account and navigating to the “My Account” section.
There is a short guide here on how to access that information!

Note: This is a secret key and links to your account. For your own security, please do not share it or expose the key publicly.

Body

The body of a submission needs to include 3 main things;

  • Information about the service itself,
  • Pickup information,
  • Drop off information.

If fields in the request are left blank, Zoom2u will assume a standard box requires a standard 3 hour delivery window, however it is best to provide as much information as possible with every request.

NameMandatoryTypeDescription
PurchaseOrderNumberNoStringUsed to add your own reference code, PO Number, or other reference number to the booking details!
ReadyDateTimeNoDateTimeUsed to specify when the package is ready for pick up.

Must be in UTC time, in ISO8601 format.
eg. YYYY-MM-DDTHH:MM:SSZ

Default if left blank is the current (local) system time.
DeliverySpeedNoStringUsed to specify the service level of the delivery; how quickly the delivery needs to be completed
- Same day
Only available if the ReadyDateTime is earlier than 12:30pm, and allows delivery any time before 8:30pm.
- 3 hour
Only available if the ReadyDateTime is earlier than 5:00pm, and requires the delivery is completed within 3hrs of the ReadyDateTime.
- VIP
The booking will be created with the highest priority and delivered as soon as possible.
Available all times of the day though no guarantee is made for deliveries ready after 9pm
VehicleTypeNoStringThe vehicle that is required to complete the delivery.
- Bike
Short deliveries, cheap, but small capacity.
- Car
Medium cost, medium capacity.
- Van
Can facilitate large deliveries.

Default if unspecified is Car
PackageTypeNoStringUsed to categorise the items being delivered.
- Documents
Can be delivered by Bikes, Cars, and Vans.
- Bag
Can be delivered by Bikes, Cars, and Vans.
- Box
Can be delivered by Cars and Vans only.
- Flowers
Can be delivered by Cars and Vans only, and only with the "3 hour" and "VIP" delivery speeds.
- Custom
All other deliveries

Default if unspecified is Custom and will generate a generic price.
PackageDescriptionNoStringA short, generic, notes field.
PickupNo*ObjectContains the pickup information (name, contact details, address, notes)

* If not provided, the default pickup location in the address book of the account is used as the pickup location.
The address of the account is used if neither of the above are provided, and an error occurs of none of the 3 are available at all.
DropoffAlwaysObjectContains the drop off location information (name, contact details, address, notes)


‘Pickup’ and ‘Dropoff’ location object details

NameTypeMandatoryDescription
ContactNameStringNoName of the contact at the pick up or delivery location.
It is best to add a business name if applicable too.
eg. "Jane Smith (ACME Company)"
EmailStringNoAn email address for the contact at the pick up or delivery location.
If a driver is unable to locate an address, they will be able to access this information to assist them.

This field can be blank if not applicable (eg. ""), but the field cannot be omitted.
PhoneStringNoA contact phone number for the pick up or delivery location.
If a driver is unable to locate an address, they will be able to access this information to assist them.

This field can be blank if not applicable (eg. ""), but the field cannot be omitted.
NotesStringNoFree text notes field relating to the pick up or drop off location specifically.
eg. "See security" or "Ring doorbell"
UnitNumberStringYes*Should be the unit number of an apartment, or the suite number of an office building.

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
StreetNumberStringYes*Street number

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
StreetStringYes*Name of the street

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
SuburbStringYes*eg. "Sydney

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
PostcodeStringYes*eg. "2000" if the postcode is "Sydney"

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
StateStringYes*State in either short, 3 character, form or full form.
eg. "NSW" or "New South Wales"

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
CountryStringYes*eg. Australia

This field can be removed if it is replaced by the FullAddress field.
See notes below for more information.
Example:
{
    "PurchaseOrderNumber":"ABCD1234",
    "PackageDescription": "1 box with some cakes",
    "ReadyDateTime": "2020-12-24T10:20:00.06Z",
    "VehicleType": "Car",
    "PackageType": "Box",
    
    "Pickup": {
        "ContactName": "John Smith",
        "Email": "[email protected]",
        "Phone": "0000 0000",
        "UnitNumber": "",
        "StreetNumber": "123",
        "Street": "Main St",
        "Suburb": "North Sydney",
        "State": "NSW",
        "Postcode": "2000",
        "Country": "Australia",
        "Notes" : ""
    },
    
    "Dropoff": {
        "ContactName": "Jane Smith",
        "Email": "[email protected]",
        "Phone": "0000 0000",
        "UnitNumber": "ACME Co.",
        "StreetNumber": "123",
        "Street": "Main St",
        "Suburb": "North Sydney",
        "State": "NSW",
        "Postcode": "2000",
        "Country": "Australia",
        "Notes" : ""
    }
}

Alternatively, for your convenience, you can choose to submit a full, concatenated, address instead of the individualised components.
When a full street address is submitted, the address MUST includes the following elements;

  • Street Number
  • Street Name
  • Suburb
  • Postcode
  • State

A booking cannot be completed if it is missing any of the above components.
The unit number or business name should be provided in the FullAddress field if applicable, but is not mandatory if it is not applicable.
Eg.

  • This is acceptable:
     "FullAddress": "610 Appleby St, Kensington, 2000, NSW",
  • This is not acceptable:
     "FullAddress": "20 Main St, NSW",
The other components of the pickup or drop off location must still be submitted. The submission, in total, would then contain these 5 strings;
  • ContactName
  • Phone
  • Email
  • Notes
  • FullAddress
Example (With FullAddress address substitution):
{
    "PurchaseOrderNumber":"ABCD1234",
    "PackageDescription": "1 box with some cakes",
    "ReadyDateTime": "2020-12-24T10:20:00.06Z",
    "VehicleType": "Car",
    "PackageType": "Box",
    
    "Pickup": {
        "ContactName": "John Smith",
        "Email": "[email protected]",
        "Phone": "0000 0000",
        "FullAddress": "610 Appleby St, Sydney, 2000, NSW",
        "Notes" : ""
    },
    
    "Dropoff": {
        "ContactName": "Jane Smith",
        "Email": "[email protected]com",
        "Phone": "0000 0000",
        "FullAddress": "ACME Co, 123 Main St, North Sydney, NSW, 2000, NSW",
        "Notes" : ""
    }
}



Response

There are 3 possible responses when creating a booking;

  • Successful requests will return a booking reference, a price confirmation, and a unique tracking URL.
  • If mandatory information is missing from the request, the response will indicate which fields need to be filled in.
  • If there are issues unrelated to the submitted data

Success

NameTypeDescription
referenceStringThe booking reference number for the booking in our system.

This will be crucial for referencing the booking in further API calls.
priceDecimalDollar value of the booking (local currency)
tracking-linkStringURL sent to the customer and the recipient to track the location of the driver and the delivery.
trackingCodeStringUnique tracking code
Example:
{
    "reference": "Z20180101999999",
    "price": 42.0,
    "tracking-link": "https://track.zoom2u.com/A1B2C3D4E",
    "trackingCode": "A1B2C3D4E"
}

 

If information is missing from the request

NameLocationTypeDescription
messageBodyStringShort error message
modelStateBodyObject / ArrayCollection of erroneous fields
getQuoteRequestmodelStateStringSpecific field that is missing.
Note: There can be multiple entries if multiple fields are missing.
Example:
{
  "message": "The request is invalid.",
  "modelState": {
    "getQuoteRequest.Pickup.Suburb":   [ "The Suburb field is required." ],
    "getQuoteRequest.Pickup.Postcode": [ "The Postcode field is required." ],
  }
}



Other issues

HTTP Status CodeMeaningDescriptionTroubleshooting
400Bad RequestThe server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).- Check the request syntax!
401UnauthorisedThe request has not been applied because it lacks valid authentication credentials for the target resource.- Check the bearer token is valid and has been submitted correctly.
- Check the url is correct
403ForbiddenThe server understood the request but refuses to authorize it.
404Not foundThe origin server did not find a current representation for the target resource or is not willing to disclose that one exists.- Check the endpoint URL to make sure it is correct.
415Unsupported media TypeThe origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource.- Check the Content-Type field has been correctly assigned
- Check the syntax of the body data is correct, and is of the same language as the Content-Type tag