GetSwift API V2

Introduction

The GetSwift API V2 allows automated access to the GetSwift 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/public/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

API Path Changes

If you have used this API before 20th August 2019, then you would be using the old path /api/v2. Since this date we have updated the path to be /api/public/v2 and new API endpoints will be added here. Any code that is working with the old path will continue to work for the duration of the v2 API, but we recommend updating to the new path when you can since new API endpoints will be on this path only.

Get a quote

POST api/public/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/public/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/public/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/public/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/public/v2/deliveries/69cc258d-c05c-4dfc-8158-6733adc528ed"
  }
}

Track an order

GET api/public/v2/deliveries/{id}

Pass any delivery id to this endpoint to view its details. To expand the StageHistory property setting the expand parameter to StageHistory will include the stages the job progressed though, including the UTC time of each stage.

Examples

Request

            
https://app.getswift.co//api/public/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/public/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/public/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/public/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/public/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/public/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/public/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/public/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/public/v2/deliveries/5fe6b4a6-39ed-4f82-8e15-2296cfd5b567"
        }
    },
    ....
    ....
    ....
    ]
}

Get driver details

GET api/public/v2/drivers/{id}

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

Examples

Request

            
https://app.getswift.co/api/public/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/public/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/public/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/public/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/public/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/public/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/public/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/public/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": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

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

{
  "EventName": "job/added",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

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": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

job/accepted
Job has been accepted by a driver
example

{
  "EventName": "job/accepted",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "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": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "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": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "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": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/finished
Job has been delivered successfully
example

{
  "EventName": "job/finished",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

job/cancelled
Job was cancelled
example

{
  "EventName": "job/cancelled",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

job/closed
Job was either completed or cancelled
example

{
  "EventName": "job/closed",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

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

{
  "EventName": "job/abandoned",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

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

{
  "EventName": "job/feedback",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    }
  }
}

job/edited
A job has been edited
example

{
  "EventName": "job/edited",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
    "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
    "Reference": "ABC123",
    "CustomerReference": "Ms Booker",
    "AbandonmentReasons": [
      "reason 1",
      "reason 2"
    ]
  }
}

driver/online
A driver has gone online
example

{
  "EventName": "driver/online",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
    "DriverName": "Mr Driver",
    "DriverPhoneNumber": null
  }
}

driver/offline
A driver has gone offline
example

{
  "EventName": "driver/offline",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
    "DriverName": "Mr Driver",
    "DriverPhoneNumber": null
  }
}

geofence/atpickup
The driver is at the pickup address
example

{
  "EventName": "geofence/atpickup",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/onway
The driver has left the pickup address
example

{
  "EventName": "geofence/onway",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/atdropoff
The driver is at the drop-off address
example

{
  "EventName": "geofence/atdropoff",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

geofence/completed
The driver has left the drop-off address
example

{
  "EventName": "geofence/completed",
  "DateStamp": "2023-03-27T05:08:47.498Z",
  "Data": {
    "Job": {
      "MerchantIdentifier": "4053734c-3e5c-4e6e-9d87-b880dbd9bd37",
      "JobIdentifier": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
      "Reference": "ABC123",
      "CustomerReference": "Ms Booker",
      "AbandonmentReasons": [
        "reason 1",
        "reason 2"
      ]
    },
    "Driver": {
      "Identifier": "01536810-51d6-4cfc-8406-abc33a517486",
      "DriverName": "Mr Driver",
      "DriverPhoneNumber": null
    },
    "Location": {
      "Longitude": 144.9013,
      "Latitude": 37.8323
    }
  }
}

smswebhook
A delivery status notification has been raised
example

{
  "mobileNumber": "+6140000000",
  "getSwiftId": "c99ef6dd-636e-480e-bbaf-04243e1b2ef2",
  "messageText": "Your order has been delivered!",
  "messageType": "complete"
}

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 GetSwift API require HTTP over SSL
429 Too Many Requests
The maximum limit for active requests has been exceeded. Please check the API response for the request limit per second as they may differ per API, and throttle your requests accordingly.
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"
    }

GetSwift error codes

All possible error codes returned by GetSwift 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
NoDataFound
No Data found for provided parameters
Unspecified
Unspecified Error
ServerError
Internal Server Error
Unauthorised
Unauthorised
RatingNotFound
Job rating not found
SkillNotFound
Job skills not found
InvalidJobId
Invalid Job ID
InvalidDriverId
Invalid Driver ID
AutoDispatchOn
Auto-dispatch is currently on. Please turn it off and try again
DriverOffline
The driver you are assigning the job to is offline
DriverJobConstraints
The driver you are assigning the job to does not satisfy one or more job constraints
VehicleCapacityError
No vehicle with enough capacity
UndefinedCapacity
Undefined capacity with provided name
InvalidCapacities
Invalid Job capacities
InvalidMetadata
Invalid metadata type
DuplicateOrderReference
Duplicate order reference