When routing or creating consignments, you must provide to MachShip both the pickup and delivery suburbs/locations. This is a guide on the multiple ways that these locations can be provided to MachShip.

Pickup and Delivery Locations

MachShip offers the following ways to specify the pickup and delivery locations for the consignment.

• Suburb and Postcode Combination
• Saved Company Location ID
• MachShip's Location ID (Suburb ID)

The pickup location and delivery location can be specified via different methods. For example, the pickup location could be provided as a saved company location while the delivery location may be specified as a suburb and postcode. You only need to specify one of these methods for both the pickup and delivery locations for generating routes and pricing. For example, if you provide a companyLocationId for the pickup location, you do not need to provide the suburb and postcode.

Suburb and Postcode Combination

MachShip uses an up-to-date suburb postcode list which you can use when specifying pickup and delivery locations. These can be specified with the location.suburb and location.postcode properties. You can also validate a suburb that a user has entered outside of routing via /apiv2/locations/GetLocations, however, this is not required as routing will also validate the entered suburbs for you.

Example of using suburb and postcodes to specify the pickup and delivery suburbs.

{
  ...
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toLocation": {
    "suburb": "sydney",
    "postcode": "2000"
  }
  ...
}

Saved Company Location ID

MachShip allows you to create saved company locations for frequently used pickup or delivery locations. These saved locations can be specified when generating routes and prices by providing the id of the appropriate saved company location. Saved company location IDs can be retrieved via our /apiv2/companyLocations endpoints.

{
  ...
  "fromCompanyLocationId": 1234,
  "toCompanyLocationId": 5346,
  ...
}

MachShip's Location ID (Suburb ID)

MachShip maintains its own list of suburbs and the IDs of these locations can be used when returning routes. Please refer to our /apiv2/locations documentation for retrieving location IDs from MachShip.

{
  ...
  "fromLocationId": 5002,
  "toLocationId": 111,
  ...
}

Pickup and Delivery Location Errors

If there are any issues with the locations provided, you will receive a response similar to below:

{
  "object": null,
  "errors": [
    {
      "validationType": "Error",
      "memberNames": [],
      "errorMessage": "From Location is invalid"
    }
  ]
}

Creating Consignments - Additional Fields

When creating consignments, there are some additional fields that can be provided that are not necessary when routing. These fields can be provided or can be taken from saved locations when saved locations are used. For example, if you use a fully populated saved location, you will not need to specify any of these fields.

These fields are required (unless specified in the saved location) for both pickup and delivery suburbs when creating a consignment:

• Name - This is the name of the location which could be the warehouse or business name or the name of your customer.
• AddressLine1 - These fields are optional and can also be retrieved from the saved location.
• Contact - This should be the contact name of the person at the pickup or delivery location.
• Phone - The phone number for the driver to call if there are any issues at the location.
• Email - A semicolon-delimited list of emails. This is validated and will throw an exception if there are any invalid email addresses.
• AddressLine2

Additional Fields Example

{
  "fromName": "My Warehouse",
  "fromContact": "Bob Jones",
  "fromPhone": "123123123",
  "fromEmail": "test@test.com",
  "fromAddressLine1": "testAddressLine1",
  "fromAddressLine2": "testAddressLine2",
  "fromLocation": {
    "suburb": "melbourne",
    "postcode": "3000"
  },
  "toName": "Customers House",
  "toContact": "Stacy Smith",
  "toPhone": "123123123",
  "toEmail": "test@test.com",
  "toAddressLine1": "testAddressLine1",
  "toAddressLine2": "testAddressLine2",
  "toLocation": {
    "suburb": "Sydney",
    "postcode": "2000"
  }
}