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
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 ).
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"
}
}
}
Book a delivery
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.
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
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.
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
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.
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
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.
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
List ratings for a job or all of a driver's jobs. Supplying only the merchant key will show all ratings.
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-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"DriverName": "Mr Driver",
"DriverPhoneNumber": null
},
"Location": {
"Longitude": 144.9013,
"Latitude": 37.8323
}
}
}
job/cancelled
Job was cancelled
example
{
"EventName": "job/cancelled",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
}
}
job/closed
Job was either completed or cancelled
example
{
"EventName": "job/closed",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"DriverName": "Mr Driver",
"DriverPhoneNumber": null
}
}
}
job/edited
A job has been edited
example
{
"EventName": "job/edited",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
}
}
driver/online
A driver has gone online
example
{
"EventName": "driver/online",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"DriverName": "Mr Driver",
"DriverPhoneNumber": null
}
}
driver/offline
A driver has gone offline
example
{
"EventName": "driver/offline",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"DriverName": "Mr Driver",
"DriverPhoneNumber": null
}
}
geofence/atpickup
The driver is at the pickup address
example
{
"EventName": "geofence/atpickup",
"DateStamp": "2023-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"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-09-25T04:19:11.404Z",
"Data": {
"Job": {
"MerchantIdentifier": "7ed6c582-0702-4095-b94b-65941cdbddd2",
"JobIdentifier": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"Reference": "ABC123",
"CustomerReference": "Ms Booker",
"AbandonmentReasons": [
"reason 1",
"reason 2"
]
},
"Driver": {
"Identifier": "ae912040-7a1e-4816-8c8e-d2e528336e1e",
"DriverName": "Mr Driver",
"DriverPhoneNumber": null
},
"Location": {
"Longitude": 144.9013,
"Latitude": 37.8323
}
}
}
smswebhook
A delivery status notification has been raised
example
{
"mobileNumber": "+6140000000",
"getSwiftId": "a4d2efd2-c2b3-461b-9e6c-70f9f7f370a2",
"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