Swift API V2

Introduction

The Swift API V2 allows automated access to the Swift proprietary logistics platform. You can obtain quotes, book deliveries, track orders and view your order history via a simple RESTful interface.

This document will explain the basics of using the API. For request and response examples click on the "Show JSON" links at the end of each section. For a more in-depth explanation of everything, please see the full technical documentation.

To get started, below is an example of the simplest JSON needed to book a delivery on Swift. Send this object as a POST request (with the "Content-Type" header set to "application/json") to https://app.getswift.co/api/v2/deliveries using your merchant API key.

        
{
    "apiKey": "MERCHANT_KEY",
    "booking":{
        "pickupDetail": {
            "address": "57 luscombe st, brunswick, melbourne"
        },
        "dropoffDetail": {
            "address": "105 collins st, 3000"
        }
    }
}            

Getting a merchant key

Before making a call you will need your own unique private merchant key. You can generate a key and enable access, as well as configure various features of the API, in your merchant's API settings.

Servers

Live: https://app.getswift.co

Get a quote

POST api/v2/quotes

This endpoint can be used to obtain time, distance and cost estimations for a job. It can also indicate driver availability for an on-demand bookings (enable this feature through your API settings ).

Examples

Request

Example of the bare minimum information we need to give you a quote.

            
{
    "apiKey":"MERCHANT_KEY",
    "booking":{
        "pickupDetail":{
            "address":"51 luscombe st, brunswick, melbourne"
        },
        "dropoffDetail":{
            "address":"101 collins st, 3000",
        }
    }
}
            

Example of the simplest possible pre-order where the delivery requires a specific finish time. A pickup time can also be supplied if needed.

            
{
    "apiKey":"MERCHANT_KEY",
    "booking":{
        "pickupDetail":{
            "address":"33 lygon st carlton"
        },
        "dropoffDetail":{
            "address":"101 collins st, 3000",
        },
        "dropoffWindow":{
            "earliestTime":"2015-3-25 3:27Z",
            "latestTime":"2015-3-25 8:27Z"
        }
    }
}
        

Response

            
{
    "quote": {
        "created": "2015-03-23T00:20:48.6940969Z",
        "start": "2015-03-25T02:56:00Z",
        "distanceKm": 1.5,
        "fee": {
            "cost": 8.61,
            "costCents": 861,
        },
        "pickup": {
            "time": {
                "average": "2015-03-25T03:11:00Z",
                "earliest": "2015-03-25T02:56:00Z",
                "latest": "2015-03-25T03:21:00Z"
            },
            "address": "33 Lygon Street, Carlton VIC 3053, Australia"
        },
        "dropoff": {
            "time": {
                "average": "2015-03-25T05:57:00Z",
                "earliest": "2015-03-25T03:27:00Z",
                "latest": "2015-03-25T08:27:00Z"
            },
            "address": "101 Collins Street, Melbourne VIC 3000, Australia"
        }
    },
    "request": {
        "reference": null,
        "deliveryInstructions": null,
        "itemsRequirePurchase": false,
        "items": null,
        "pickupTime": null,
        "pickupDetail": {
            "name": null,
            "phone": null,
            "email": null,
            "description": null,
            "address": "33 lygon st carlton"
        },
        "dropoffWindow": {
            "earliestTime": "2015-03-25T03:27:00Z",
            "latestTime": "2015-03-25T08:27:00Z"
        },
        "dropoffDetail": {
            "name": null,
            "phone": null,
            "email": null,
            "description": null,
            "address": "101 collins st, 3000"
        }
    }
}
Warning: Please keep your API keys private. If your key is made public, it will allow people to book deliveries under your account. This could result in unwanted charges and most likely the deactivation of your key. Please don't expose the key by connecting to the API via a client, always make calls via a server.

Book a delivery

POST api/v2/deliveries

Booking a delivery is very similar to getting a quote. When booking, you will receive back details of the delivery as well as time estimates and price. You can open the examples by clicking on the link below, or see much more detailed information provided in the technical documentation.

Examples

Request

Below is a simple job booking example. As no pickup or finish time is specified, this delivery will be sent to our drivers immediately. Please note that only the pickup and drop-off addresses are mandatory.

            
{
    "apiKey": "MERCHANT_KEY",
    "booking":{
        "pickupDetail": {
            "name": "Rupert",
            "phone": "1234567890",
            "address": "57 luscombe st, brunswick, melbourne"
        },
        "dropoffDetail": {
            "name": "Igor",
            "phone": "0987654321",
            "address": "105 collins st, 3000"
        }
    }
}            

Response

The response contains pricing and time estimations (quote), a record of the delivery including the reference number and tracking links (request), as well as a copy of the data used to create the booking (delivery).

            
{
    "quote": {
        "created": "2015-03-17T00:44:29.4172047Z",
        "start": "2015-03-17T00:44:00Z",
        "distanceKm": 1.3,
        "fee": {
            "cost": 7.97,
            "costCents": 797,
        },
        "pickup": {
            "time": {
                "average": "2015-03-17T00:59:00Z",
                "earliest": "2015-03-17T00:44:00Z",
                "latest": "2015-03-17T01:09:00Z"
            },
            "address": "67 Brunswick Street, Fitzroy VIC 3065, Australia"
        },
        "dropoff": {
            "time": {
                "average": "2015-03-17T01:21:00Z",
                "earliest": "2015-03-17T00:59:00Z",
                "latest": "2015-03-17T01:44:00Z"
            },
            "address": "105 Collins Street, Melbourne VIC 3000, Australia"
        }
    },
    "delivery": {
        "created": "2015-03-17T00:44:29.8390888Z",
        "id": "4d9b9e22-1f0f-4b23-87bd-91b3938561ad",
        "reference": "476",
        "pickupLocation": {
            "name": "Rupert",
            "address": "67 Brunswick Street, Fitzroy VIC 3065, Australia",
            "phone": "1234567890"
        },
        "dropoffLocation": {
            "name": "Igor",
            "address": "105 Collins Street, Melbourne VIC 3000, Australia",
            "phone": "0987654321"
        },
        "lastUpdated": "2015-03-17T00:44:29.8390888Z",
        "currentStatus": "Received",
        "driver": null,
        "items": [],
        "pickupTime": null,
        "dropoffTime": {
            "earliestTime": "2015-03-17T00:59:00Z",
            "latestTime": "2015-03-17T01:44:00Z"
        },
        "deliveryInstructions": "",
        "trackingUrls": {
            "www": "https://app.getswift.co/Tracking/TransportJob/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567",
            "api": "https://app.getswift.co/api/v2/deliveries/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567"
        }
    },
    "request": {
        "reference": null,
        "deliveryInstructions": null,
        "itemsRequirePurchase": false,
        "items": null,
        "pickupTime": null,
        "pickupDetail": {
            "name": "Rupert",
            "phone": "1234567890",
            "email": null,
            "description": null,
            "address": "67 brunswick st, melbourne"
        },
        "dropoffWindow": null,
        "dropoffDetail": {
            "name": "Igor",
            "phone": "0987654321",
            "email": null,
            "description": null,
            "address": "105 collins st, 3000"
        }
    }
}
            

Future order request

Below is an example of a "future" booking, or pre-order. You can specify a pickup time and/or a delivery window.

If a delivery window is specified but a pickup time is not, the pickup time will be calculated based on your other settings and historical data.

Note: Dates are provided in UTC time, see below for an exmaple of the correct format for this.

            
{
    "apiKey":"{{merchant1key}}",
    "booking":{
        "pickupDetail":{
            "address":"101 collins st, melbourne"
        },
        "pickupTime":"2016-1-4 14:27:00Z",
        "dropoffDetail":{
            "address":"101 collins st, 3000",
        },
        "dropoffWindow":{
            "earliestTime":"2016-1-4 15:27Z",
            "latestTime":"2016-1-4 16:27Z"
        }
    }
}            

Cancel a delivery

POST api/v2/deliveries/cancel

Cancels an active delivery

Examples

Request

            
{
    "apiKey": "MERCHANT_KEY",
    "jobId":"38befd2d-8c4d-498a-a1ce-07a1c9dde15e",
    "cancellationNotes" : "Customer left town in a hurry"
}            

Response

A succesful call returns a delivery

            
{
  "created": "2016-02-13T04:05:46.73Z",
  "id": "69cc258d-c05c-4dfc-8158-6733adc528ed",
  "reference": "12345",
  "pickupLocation": {
    "name": null,
    "address": "672 Flinders St, Docklands VIC 3008, Australia",
    "phone": null
  },
  "dropoffLocation": {
    "name": null,
    "address": "670 Flinders St, Docklands VIC 3008, Australia",
    "phone": null
  },
  "lastUpdated": "2016-02-13T08:03:26.0344596Z",
  "currentStatus": "Cancelled",
  "driver": {
    "identifier": "79b56c9c-22fe-449b-b0ef-4a0091aa385e",
    "name": "Keef U",
    "phone": "8888888888",
    "photoUrl": "https://app.getswift.co/Image/GetDriverPhoto?Identifier=79b56c9c-22fe-449b-b0ef-4a0091aa385e"
  },
  "items": [],
  "pickupTime": "2016-02-13T04:07:00Z",
  "dropoffTime": {
    "earliestTime": "2016-02-13T04:05:00Z",
    "latestTime": "2016-02-13T05:05:00Z"
  },
  "deliveryInstructions": null,
  "trackingUrls": {
    "www": "https://app.getswift.co/t/HITD",
    "api": "https://app.getswift.co/api/v2/deliveries/69cc258d-c05c-4dfc-8158-6733adc528ed"
  }
}
            

Track an order

GET api/v2/deliveries/{id}

Pass any delivery id to this endpoint to view its details.

Examples

Request

            
https://app.getswift.co//api/v2/deliveries/11044285-ce65-459e-bfe0-4e0a2b4df039
        

Response

            
{
    "created": "2015-03-13T03:05:42.71",
    "id": "11044285-ce65-459e-bfe0-4e0a2b4df039",
    "reference": "468",
    "pickupLocation": {
        "name": "Axl",
        "address": "57 Luscombe Street, Brunswick VIC 3056, Australia",
        "phone": "456456456"
    },
    "dropoffLocation": {
        "name": "Alejandro",
        "address": "105 Collins Street, Melbourne VIC 3000, Australia",
        "phone": "1234567890"
    },
    "lastUpdated": "2015-03-13T03:06:45.35",
    "currentStatus": "Cancelled",
    "driver": null,
    "items": [ ],
    "pickupTime": "2015-03-13T03:05:00",
    "dropoffTime": {
        "earliestTime": "2015-03-13T03:14:00",
        "latestTime": "2015-03-13T03:30:00"
    },
    "deliveryInstructions": "",
    "trackingUrls": {
        "www": "https://app.getswift.co/Tracking/TransportJob/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567",
        "api": "https://app.getswift.co/api/v2/deliveries/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567"
    }
}            

Possible values of "currentStage" are...
Received - This is a new delivery and has not been accepted by the driver
Accepted - A driver has committed to the job
PickedUp - The item(s) have been picked up, or the driver is en route to the customer
Completed - The item(s) have been delivered
Cancelled - The delivery was cancelled

View delivery history

GET api/v2/deliveries/...

Retrieve your past and present deliveries as well as future pre-orders.

Filters available are...
Active - Jobs that are currently in progress
All - Your entire delivery history
Successful - Deliveries that have completed successfully
Cancelled - All cancelled jobs

Note that the maximum paging size per call is limited to 40 records

Examples

Request

The following call will list your entire order history including currently active orders

            
https://app.getswift.co/api/v2/deliveries?apiKey=MERCHANT_KEY
            

This example will list your cancelled orders with 3 orders per page including currently active orders, starting from the 1st April 2015

            
https://app.getswift.co/api/v2/deliveries?apiKey=MERCHANT_KEY&startDate=2015-01-04T02:08:32.997&filter=Cancelled&pageSize=3
            

Response

The results returned are wrapped in a paged list object, for example

Please note, the list of items for each delivery will be blank in this list. To see delivery items you will need to load an individual delivery.

            
{
    "currentPage": 1,
    "pageCount": 2,
    "pageSize": 10,
    "totalCount": 58,
    "firstPageUrl": "https://app.getswift.co/api/v2/deliveries?apiKey=f3030831-f19f-4686-9dd3-3353925e9bfc&pageNumber=1&pageSize=0&filter=Cancelled&startDate=2015-01-04T02:08:32.9970000Z",
    "previousPageUrl": "",
    "nextPageUrl": "https://app.getswift.co/api/v2/deliveries?apiKey=f3030831-f19f-4686-9dd3-3353925e9bfc&pageNumber=2&pageSize=0&filter=Cancelled&startDate=2015-01-04T02:08:32.9970000Z",
    "lastPageUrl": "https://app.getswift.co/api/v2/deliveries?apiKey=f3030831-f19f-4686-9dd3-3353925e9bfc&pageNumber=2&pageSize=0&filter=Cancelled&startDate=2015-01-04T02:08:32.9970000Z",
    "data": [
    {
        "created": "2015-03-13T03:05:42.71",
        "id": "11044285-ce65-459e-bfe0-4e0a2b4df039",
        "reference": "468",
        "pickupLocation": {
            "name": "James",
            "address": "123 Luscombe Street, Brunswick VIC 3056, Australia",
            "phone": "456456456"
        },
        "dropoffLocation": {
            "name": "Joel",
            "address": "105 Collins Street, Melbourne VIC 3000, Australia",
            "phone": "1234567890"
        },
        "lastUpdated": "2015-03-13T03:06:45.35",
        "currentStatus": "Cancelled",
        "driver": null,
        "items": [ ],
        "pickupTime": "2015-03-13T03:05:00",
        "dropoffTime": {
            "earliestTime": "2015-03-13T03:14:00",
            "latestTime": "2015-03-13T03:30:00"
        },
        "deliveryInstructions": "",
        "trackingUrls": {
            "www": "https://app.getswift.co/Tracking/TransportJob/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567",
            "api": "https://app.getswift.co/api/v2/deliveries/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567"
        }
    },
    ....
    ....
    ....
    ]
}            

Get driver details

GET api/v2/drivers/{id}

Pass a driver identifier to this endpoint to view an individual driver's details.

Examples

Request

            
https://app.getswift.co/api/v2/drivers/79b56c9c-22fe-449b-b0ef-4a0091aa385e
        

Response

            
{
  "identifier": "79b56c9c-22fe-449b-b0ef-4a0091aa385e",
  "name": "Mr Driver",
  "phone": "1234567890",
  "photoUrl": "https://app.getswift.co/Image/GetDriverPhoto?Identifier=79b56c9c-22fe-449b-b0ef-4a0091aa385e"
}            

List drivers

GET api/v2/drivers?ApiKey={ApiKey}&Filter={Filter}.

List all drivers for your merchant, optionally filtered by status.

Filters available are...
All - All drivers
OnlineNow - Drivers who are currently working
Activated - Drivers who are can go online
Invited - Drivers waiting to be approved

Examples

Request

This example will list all driver currently online

            
https://app.getswift.co/api/v2/drivers?apiKey=MERCHANT_KEY&filter=OnlineNow
            

Response

            
[
  {
    "identifier": "27e3a7d4-3e6d-492b-a268-d54cfc3f361a",
    "name": "Mr Driver",
    "phone": "1234567890",
    "photoUrl": "https://app.getswift.co/Image/GetDriverPhoto?Identifier=27e3a7d4-3e6d-492b-a268-d54cfc3f361a"
  },
  {
    "identifier": "7427716a-5a53-478e-a829-1a1ceb54cf85",
    "name": "Ms Driver",
    "phone": "0987654321",
    "photoUrl": "https://app.getswift.co/Image/GetDriverPhoto?Identifier=7427716a-5a53-478e-a829-1a1ceb54cf85"
  },
  {
    "identifier": "9aad0b23-27f7-4b72-8d9f-3e3e80ad9179",
    "name": "Joel Smith",
    "phone": "1234567891",
    "photoUrl": "https://app.getswift.co/Image/GetDriverPhoto?Identifier=9aad0b23-27f7-4b72-8d9f-3e3e80ad9179"
  },
    ...
    ...
    ...
]            

Driver proximity

GET api/v2/driverproximity....

Find the distances of your drivers to a particular location. Only drivers with free capacity will be returned.

Warning: This endpoint should not be frequently polled to get driver locations. If this is abused your key will be de-activated. Please talk to us if you need more details or alternative options.

Examples

Request

            
https://app.getswift.co/api/v2/driverproximity?apiKey=MERCHANT_KEY&Latitude=-37.7966&Longitude=144.97877
            

Response

            
[
    {
    "driverIdentifier": "a0334912-6461-4685-bd6c-4067bf49ec6f",
    "distanceKm": 2.006485992879639
    },
    {
    "driverIdentifier": "79b56c9c-22fe-449b-b0ef-4a0091aa385e",
    "distanceKm": 5.843756348
    }
]

Job ratings

GET api/v2/ratings....

List ratings for a job or all of a driver's jobs. Supplying only the merchant key will show all ratings.

Examples

Request

This example will list all ratings for a job

            
https://app.getswift.co/api/v2/ratings?apiKey=MERCHANT_KEY&jobId=2c049259-638f-4361-a018-52cb51571960
            

Response

            
{
  "currentPage": 1,
  "pageCount": 1,
  "pageSize": 1,
  "totalCount": 1,
  "firstPageUrl": "",
  "previousPageUrl": "",
  "nextPageUrl": "",
  "lastPageUrl": "",
  "data": [
    {
      "identifier": "0f941522-7496-421e-b233-48de307c423b",
      "jobId": "2c049259-638f-4361-a018-52cb51571960",
      "created": "2015-12-14T00:43:31.387",
      "comments": "What a nice driver!",
      "percentageRating": 80
    }
  ]
}

Webhooks

Http webhooks allow your web application to be notified when various events happen in GetSwift.

You can register your URL with the events below via your merchant's webhooks settings or on a job-by-job basis via the api/v2/deliveries endpoint. We will provide basic information with each event. If you require more detailed data, make a call to the appropriate API endpoint using the identifiers provided.

job/change
Any change was made to a job, eg: new job, driver accepted, completed, edited etc.
example

{
  "EventName": "job/change",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/added
A new job has been added to Swift
example

{
  "EventName": "job/added",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/available
A job has become available for a driver to accept, this could be because job is new or an existing job has been abandoned
example

{
  "EventName": "job/available",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/accepted
Job has been accepted by a driver
example

{
  "EventName": "job/accepted",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/driveratpickup
The driver has indicated that they are at the pickup address
example

{
  "EventName": "job/driveratpickup",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/onway
The driver has indicated that they are en route to the customer
example

{
  "EventName": "job/onway",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/driveratdropoff
The driver has indicated that they are at the drop-off address
example

{
  "EventName": "job/driveratdropoff",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/finished
Job has been delivered successfully
example

{
  "EventName": "job/finished",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/cancelled
Job was cancelled
example

{
  "EventName": "job/cancelled",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/closed
Job was either completed or cancelled
example

{
  "EventName": "job/closed",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/abandoned
The driver has removed themselves from their job
example

{
  "EventName": "job/abandoned",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

job/feedback
The customer has provided a comment about their completed job
example

{
  "EventName": "job/feedback",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    }
  }
}

job/edited
A job has been edited
example

{
  "EventName": "job/edited",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker"
  }
}

driver/online
A driver has gone online
example

{
  "EventName": "driver/online",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
    "DriverName": "Mr Driver"
  }
}

driver/offline
A driver has gone offline
example

{
  "EventName": "driver/offline",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
    "DriverName": "Mr Driver"
  }
}

geofence/atpickup
The driver has indicated that they are at the pickup address
example

{
  "EventName": "geofence/atpickup",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/onway
The driver has indicated that they are en route to the customer
example

{
  "EventName": "geofence/onway",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/atdropoff
The driver has indicated that they are at the drop-off address
example

{
  "EventName": "geofence/atdropoff",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/completed
Job has been delivered successfully
example

{
  "EventName": "geofence/completed",
  "DateStamp": "2017-02-21T14:13:03.515Z",
  "Data": {
    "Job": {
      "JobIdentifier": "a141920b-dd83-4d87-900b-2fcc29d41010",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker"
    },
    "Driver": {
      "Identifier": "3b0a8b2b-9c18-4536-8323-567c96bb5646",
      "DriverName": "Mr Driver"
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

Technical notes

  • Much more detailed technical documentation can be found here.
  • Post requests should ensure that Content-Type: application/json is specified
  • All times and dates should be in ISO_8601 format, eg: 2015-3-23T14:05:00+11:00 for local time or 2015-3-23T3:05:00Z for GMT. This is a very common format and is used by javascript, for example 1:45PM 28/1/2015 UTC time would be "2015-1-28 13:45:0.0Z". More information can be found here
  • All times and dates returned in response objects will be in UTC time, regardless of the time zone used when booking
  • Addresses can be provided to us as a simple line of text (eg: "51 High St, Prahran"). If the address is provided this way, we will geocode and validate them on our server. It is highly recommended that you geocode addresses yourself before sending to the API though, this way we will ensure that the address is correct. We can accept google's geocoding output format (info here). Address search components are relatively easy to implement in javascript using the Google Maps API. Some more info here.
  • When sending us non-geocoded addresses, we will send you back the full validated address in the quote response. We recommend you display this address to your customer in order verify that we have geocoded it correctly before placing a booking
  • We recommend testing the API with the Postman packaged app (can provide some example collections on request). You could also have a play with our (untested) swagger docs

HTTP error codes

In the event of an error or any validation problems, the API will return a standard HTTP response code and a JSON packet containing a unique code and a description of the problem.

HTTP error code responses

  • 200 OK
  • 400 Bad request
    All validation errors or unsuccessful calls will come back as 400 with a message
  • 401 Unauthorized
    This will be caused by an incorrect merchant key, or delivery id
  • 403 HTTPS Required
    All calls to the Swift API require HTTP over SSL
  • 500 Internal server error
    Something terrible has happened on our server, please contact us if this error occurs

All validation and other error messages are returned through the 400 Bad request. The response will include an error code as well as a message describing the error. For example:

            
    {
        "message": "We are sorry, all of our drivers nearby are busy. Please try again in a few minutes"
        "code": "AtCapacity"
    }
                
            
    {
        "message": "No pickup phone number supplied"
        "code": "NoPickupPhone"
    }
                

Swift error codes

All possible error codes returned by Swift are

  • AtCapacity
    We are sorry, all of our drivers nearby are busy. Please try again in a few minutes
  • DeliveryNotFound
    Delivery not found
  • NoPickupDeets
    No pickup details supplied
  • NoDropoffDeets
    No destination details supplied
  • DeliveryWindowFullInfo
    Please supply earliest AND latest time for the delivery time window
  • NoEarliestDeliveryWindow
    Earliest delivery time window should be specified
  • NoLatestDeliveryWindow
    Latest delivery time window should be specified
  • InvalidDeliveryWindow
    Invalid delivery time window
  • PastDeliveryWindow
    Delivery time window is in the past
  • NoDropoff
    No drop-off details supplied
  • NoPickup
    No pickup details supplied
  • InvalidPickupAddress
    Pickup address cannot be validated
  • InvalidDropoffAddress
    Destination address cannot be validated
  • NoData
    No Data
  • Unspecified
    Unspecified Error
  • ServerError
    Internal Server Error
  • Unauthorised
    Unauthorised
  • RatingNotFound
    Job rating not found