Introduction

Resources

Introduction

Overview

To get started using the SnapGrab API:

Create a Merchant account
Locate your API token key and API test token key.

What can the API do?

The SnapGrab API provides a simple RESTful interface to generate delivery quotes, book deliveries on the SnapGrab platform, view deliveries, cancel deliveries and track deliveries.

You can use the SnapGrab API to utilize our fleet of drivers to get orders or packages delivered in as little as 60 minutes within our geographical delivery zone currently servicing the following city:

Montréal, Qc, Canada

Here is what developers most typically do with the API:

Prepare a delivery quote for one-hour delivery by submitting two addresses to the endpoint.
Create a delivery order in the SnapGrab network if the quote is satisfactory.
Track status updates on SnapGrab deliveries by submitting the unique order ID for each created delivery order.

What do businesses get delivered with the API?

With the SnapGrab API, you can delivery most items that can normally be carried around by the average person. Please review our API terms, shipping policy and Partner code of conduct for more information.

Authentication

All endpoints provided by the SnapGrab are in relation to a specific Merchant partner. You will need your API token key in each request.

Server

The base URL is: https://api.snapgrabdelivery.com/v1/

Test Mode

In order to facilitate the integration of our API, we provide you with a test mode. Using your test API key found in the settings of your Merchant dashboard will enable you to exercise all the endpoints without being charged. The deliveries you request in test mode will not be carried out by a real delivery driver.

Please switch between your live and test key to switch from live to test mode.

Live Key

To obtain a valid live key, update your payment method in the Settings page of the Merchant dashboard. Once you have a valid payment method on file, your live key will be valid.

IMPORTANT: Your live key is sensitive data. Treat it like a password and do not share it with parties outside your direct control. Your API keys gives you direct access to the SnapGrab API on your behalf.

Versioning

Versioning allows us to provide developers with a consistent experience.

All endpoints are prefixed with a version such as /v1. This version refers to the overall layout of the endpoint and response standards.

Addresses

Please format the dropoff address in the following format:

Street Address, City, Province, Postal Code

Important: It is recommended to provide the SnapGrab API with Google Maps generated addresses or Google Maps formatted addresses to ensure successful geocoding by us.

Any other information such as door codes, buzzer codes and apartment numbers should be added in the "Instructions" field. Any extra information in the "DropOffAddress" field may result in a malformed address format and our system may not be able to detect the location accurately or at all.

Requests

Typical POST request structure is as follows

{
  "Key":"26cac56d-1d00-4c73-827e-4f9a66473445";
  ...
}

Responses

The SnapGrab API uses HTTP status codes to indicate the status of your requests.

All responses are in JSON.

201 - Successful
400 - Validation or processing error (See error section)
401 - Unauthorized. Your API is wrong or missing.

Error codes

The SnapGrab API separates all errors into 2 types: validation errors (Code 1xx) or processing errors (code 2xx). Both types of errors return 400 HTTP status codes and have the following structure.

{
  "Code":"101";
  "Message":"DropOff address is not located in serviced delivery area."
}

VALIDATION ERRORS

Error Code	Message	Fix
101	DropOff address is not located in serviced delivery area	This address cannot be delivered to. Check out our delivery zone.
102	Delivery has been scheduled for more than 7 days into the future	You cannot scheduled a delivery for more than 7 days into the future. Select a closer delivery date and time.
103	Delivery should be scheduled at a minimum of 5 minutes into the future	The scheduled delivery time must be at least 5 minutes into the future. Select a later date and time.
104	DropOff time is not within SnapGrab's operating times	SnapGrab operates between 10AM and 10PM. Select a schedule delivery time between these times.
105	Invalid DropOff address format, must be a Google recognized format	Please follow Google maps address format.
106	Missing information fields, DropOff customer name should be a minimum of 2 characters long	The customer name must be at least 2 characters. Please review the name.
107	Missing informations fields, the DropOff phone number is invalid	The customer's phone number should be 10 digits long.
108	Invalid Information fields. Instructions should be less than 65 characters.	The instructions are too long. Please limit the value to less than 65 characters.
109	User does not have a valid payment method on file.	Please add a valid payment card in your merchant account dashboard.
110	Invalid param "Param_name"	Please review your parameters.

PROCESSING ERRORS

Error Code	Message	Fix
201	Your Merchant payment card was declined	Please use a valid payment method in your Merchant account dashboard.
202	Token is not valid or is deprecated	Request a new token through /order/prepare
203	Order is not found	The order number is incorrect
204	Order is already cancelled	This order is already in the cancelled stage
205	Order cannot be cancelled anymore	The order is not in a cancellable stage anymore

HTTP ERROR CODES

401 - Unauthorized. Authentication was incorrect. Please verify your API key.
404 - Not found.
500 - Internal Server Error. We were unable to process this request.

Resources

Getting a Delivery Quote

The first step to creating a delivery request using the SnapGrab API is to generate a delivery quote. This quote will help you or your customers make easy decisions on delivery fees and availability. The fee generated is based on multiple factors such as distance, complexity of the delivery, driver availability, and road traffic.

Pickups by driver will always be done in the 60 minutes following the scheduled pick-up time. The delivery will be executed immediately after the order has been picked up.

Note*: The scheduled pickup time is not the exact time the delivery driver will present himself at your pick-up location.

The delivery quote is valid for a period of 30 minutes from when it is requested.

*IMPORTANT* Please format the drop-off address in the following format:

Street Address, City, Province, Postal Code

Important: It is recommended to provide the SnapGrab API with Google Maps generated addresses or Google Maps formatted addresses to ensure successful geocoding by us.

Any other information such as door codes, buzzer codes, apartment numbers, etc. should be added in the "Instructions" field. Any extra information in the "DropOffAddress" field may result in a malformed address format and our system may not be able to detect the location accurately or at all.

REQUEST INFORMATION

POST: /order/prepare

{
  "Key": "26cac56d-1d00-4c73-827e-4f9a66473445"
  "ScheduledAt": "2020-08-01T23:35:36.628Z"
  "DropOffAddress": "1600 Henri-Bourassa Boulevard West, Montreal, QC, Canada";
  "CustomerName": "Tyler Bryant";
  "CustomerPhone": "5141234567";
  "CustomerEmail": "Tyler@SnapGrab.com";
  "Instructions": "Unit 1";
  "LargeOrder": false,
  "BringBack": false,
}

Body Parameters	REQUEST INFORMATION	Required
Key	String - Your unique identifier key	Yes
ScheduledAt	String - The time you want the delivery to start at. ISO format. Must be a minimum of 5 minutes in the future and less than 7 days in the future.	Yes
DropOffAddress	String.- The drop-off address for a potential delivery in a Google maps understandable format	Yes
CustomerName	String - The drop-off recipient's full name	Yes
CustomerPhone	String - The 10 digit drop-off recipient's contact phone number	Yes
CustomerEmail	String - The drop-off recipient's email	Yes
Instructions	REQUEST INFORMATION	REQUEST INFORMATION
LargeOrder	Boolean - Indicate if the delivery contain large item	No
BringBack	Boolean - Indicate if delivery driver must return items from the drop-off address back to your pick-up location	No

RESPONSE INFORMATION

{
  "Token": "21bd6cb0-89fa-4738-a659-7667f0446f3d"
  "Prices": {
    "BaseFare": 12.99;
    "DistanceFare": 0.50;
    "LargeOrderFare": 0;
    "SurgeTime": false;
    "tvq": 1.35;
    "tps": 0.67;
    "TotalAmount": 15.51;
    "DeliveryCharge": 13.49;
    "Distance": 3200;
    "ServiceFee": 0;
  }
}

Body Parameters	Description
Token	String - Your delivery quote token
BaseFare	Number - The base fare of your delivery quote
DistanceFare	Number - The fare for distance charges
LargeOrderFare	Number - The fare for a large order
SurgeTime	Boolean - Surge times are for period of high order volume and may increase the base fare for a delivery
tvq	Number - Local Québec sales tax
tps	Number - Federal sales tax
TotalAmount	Number - The total amount including all taxes
DeliveryCharge	Number - the fare including the base fare, distance fare and surge time fare.
Distance	Number - The distance from pickup to drop-off in meters.
ServiceFee	The service fee fare (if applicable)

ERRORS

Error code	Description
101	The drop-off address is not within SnapGrab's serviced delivery zone
102	The scheduled start time must be less than 7 days in the future.
103	The scheduled start time must be more than 5 minutes in the future.
104	The drop-off time must be between 10:00 EST and 22:00 EST
105	The drop-off address is not recognized by us. Please use a Google formatted address.
106	Missing information field. Drop-off name must be equal or greater than 2 characters.
107	Missing information field. Drop-off phone number is invalid. Drop-off phone number is 10 digits.
108	Missing information field. No instruction was given.
109	Merchant does not have a valid payment card on file in their account.
110	Invalid parameters. "Param_name"

Creating a Delivery

Once you have received your delivery quote, it's time to create a real delivery in the SnapGrab platform. To do so, you will need to provide your unique live API key and the Token key generated in your quote. Remember that delivery Tokens are only active for 30 minutes from the moment your delivery quote request was initially made. Once you create your delivery, the delivery fee will be deducted from your payment method listed in your Merchant dashboard's settings.

REQUEST INFORMATION

POST: /order

{
  "Key": "26cac56d-1d00-4c73-827e-4f9a66473445";
  "Token": "21bd6cb0-89fa-4738-a659-7667f0446f3d";
}

Body Parameters	Description	Required
Key	String - Your unique identifier key	Yes
Token	String - Your delivery quote token	Yes

RESPONSE INFORMATION

{
  "Id": 3456;
  "TrackingLink": "https://api.snapgrabdelivery.com/track/7df5805d-3ce8-4dc9-b229-1440a013c3b7";
  "CustomerName": "Tyler Bryant";
  "DeliveryAddress": "1600 Henri-Bourassa Boulevard West, Montreal, QC, Canada";
  "CustomerPhone": "5141234567";
  "Instructions": "Unit 1";
  "ScheduledTime": "2020-08-01T23:35:36.628Z";
  "DeliveryStage": "Received";
  "DriverName": "null";
}

Body Parameters	Description
Id	String - Your delivery order number
TrackingLink	String - The tracking link for real time GPS order tracking
CustomerName	String - The drop-off recipient's full name
DeliveryAddress	String.- The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhone	String - The 10 digit drop-off recipient's contact phone number
Instructions	String - Any other important information such as apartment number or buzzer code
ScheduledTime	String - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStage	String - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverName	String - The name of the driver executing this delivery.

ERRORS

Error code	Description
201	The merchant's payment card was declined.
202	The delivery quote token does not exist or is deprecated.

Track an order

Once your delivery is successfully placed in the SnapGrab platform, you can retrieve specific information about it.

REQUEST INFORMATION

POST: /order/track

{
  "Key": "26cac56d-1d00-4c73-827e-4f9a66473445"
  "Id": 3456
}

Body Parameters	Description	Required
Key	String - Your unique identifier key	Yes
Id	String - Your delivery order number	Yes

RESPONSE INFORMATION

{
  "Id": 3456;
  "TrackingLink": "https://api.snapgrabdelivery.com/track/7df5805d-3ce8-4dc9-b229-1440a013c3b7";
  "CustomerName": "Tyler Bryant";
  "DeliveryAddress": "1600 Henri-Bourassa Boulevard West, Montreal, QC, Canada";
  "CustomerPhone": "5141234567";
  "Instructions": "Unit 1";
  "ScheduledTime": "2020-08-01T23:35:36.628Z";
  "DeliveryStage": "Received";
  "DriverName": "Steve Leonard";
}

Body Parameters	Description
Id	String - Your delivery order number
TrackingLink	String - The tracking link for real time GPS order tracking
CustomerName	String - The drop-off recipient's full name
DeliveryAddress	String.- The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhone	String - The 10 digit drop-off recipient's contact phone number
Instructions	String - Any other important information such as apartment number or buzzer code
ScheduledTime	String - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStage	String - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverName	String - The name of the driver executing this delivery.

ERRORS

Error code	Description
203	Order not found

Cancelling an order

After your delivery is placed in the SnapGrab platform, you can cancel an ongoing order. Delivery fees may still apply.

REQUEST INFORMATION

POST: /order/cancel

{
  "Key": "26cac56d-1d00-4c73-827e-4f9a66473445"
  "Id": 3456;
  "Reason": "Customer isn't home right now";
}

Body Parameters	Description	Required
Key	String - Your unique identifier key	Yes
Id	String - Your unique identifier for the delivery	Yes
Reason	String - The reason why the order is being cancelled	No

RESPONSE INFORMATION

{
  "Id": 3456;
  "CustomerName": "Tyler Bryant";
  "DeliveryAddress": "1600 Henri-Bourassa Boulevard West, Montreal, QC, Canada";
  "CustomerPhone": "5141234567";
  "Instructions": "Unit 1";
  "ScheduledTime": "2020-08-01T23:35:36.628Z";
  "DeliveryStage": "Cancelled";
  "DriverName": "Steve Leonard";
}

Body Parameters	Description
Id	String - Your delivery order number
TrackingLink	String - The tracking link for real time GPS order tracking
CustomerName	String - The drop-off recipient's full name
DeliveryAddress	String - The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhone	String - The 10 digit drop-off recipient's contact phone number
Instructions	String - Any other important information such as apartment number or buzzer code
ScheduledTime	String - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStage	String - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverName	String - The name of the driver executing this delivery.

ERRORS

Error code	Description
203	Order not found - Your order number might be incorrect
204	Oder is already in the cancelled stage
205	Order cannot be cancelled - View the cancelation policy

List Orders

You can pull and list confirmed orders from the SnapGrab platform to view which deliveries have been placed successfully. This is especially useful while in Test mode to verify if your API requests were a success.

REQUEST INFORMATION

POST: /orders

{
  "Key": "26cac56d-1d00-4c73-827e-4f9a66473445";
  "Offset": 0;
  "OrderType": ["Booking"];
  "Limit": 20;
  "DeliveryStage": ["Received","Completed"];
  "SortBy": "ScheduledAt";
  "OrderBy": "Desc";
  "Period": ["2020-05-22T08:15:07.943Z","2020-08-14T16:15:07.943Z"];
}

Body Parameters	Description	Required
Key	String - Your unique identifier key	Yes
Offset	Number - It specifies the offset of the first row (order) you want returned. Note: The offset for the first row is 0 and not 1. Default: 0	No
Limit	Number - The total number of row (orders) you want returned. Maximum:20. Default:20.	No
DeliveryStage	Array - If present only deliveries in specified stages will be returned. Accepted values are: "Received", "Accepted", "OnWay", "Completed", "Cancelled". Default is All	No
SortBy	String - Determines the field for sorting. Accepted values are: "Id" or "ScheduledAt". Default: "Id".	No
OrderBy	String - Determines the sorting order for the list. Accepted values are: "Asc" or "Desc". Default: "Desc".	No
Period	Array - specified a minimum and maximum date and time for an order list. Accepted value is 2 elements in array. Each element should be in ISO formatted date/time.	No
OrderType	Array - If present only orders of specified type will be returned. Accepted values are: "Booking", "Menu", "Trip". Default: All	No

RESPONSE INFORMATION

{
  "Count":2,
  "Orders":
  [
    {
      "Id":"2891",
      "TrackingLink":"https://sgswiftadmin.snapgrabdelivery.com/track/0706cd14-b af0-4e59-a242-7df6d38e6ab8",
      "CustomerName":"Terry",
      "DeliveryAddress":"1600 Henri-Bourassa Boulevard West, Montreal, QC, Canada",
      "CustomerPhone":"1231231231",
      "Instructions":"Unit 4",
      "ScheduledTime":"2020-05-22T08:15:07.943Z",
      "DeliveryStage":"Completed",
      "DriverName":null,
    },
    {
      "Id":"2873",
      "TrackingLink":"https://sgswiftadmin.snapgrabdelivery.com/track/ab9cb42e-8 a8b-4446-b05a-c71336e02a2b",
      "CustomerName":"Fred Jordan",
      "DeliveryAddress":"1000 Rue Ottawa, Montréal, QC H3C 0P3, Canada"
      "CustomerPhone":"1231231231",
      "Instructions":"Unit 1",
      "ScheduledTime":"2020-05-22T09:15:07.943Z",
      "DeliveryStage":"Completed",
      "DriverName":"Henry Brown",
    }
  ]
}

Body Parameters	Description
Count	Number - The total number of order matching the criteria
Orders	String - Array of orders. Order format is the same as /order/track endpoint.

ERRORS

Error code	Description
110	Invalid Parameters. "Param_name".

Customer unavailable at delivery

When a delivery driver reaches the drop-off location, the delivery driver will spend up to 5 minutes attempting to locate the customer. If a drop-off recipient is not available or not home, the delivery driver will need to mark the delivery as "Customer unavailable.". At this moment, a return route to the merchant's pickup location will start for which delivery fees may apply. A delivery driver will not be able to mark a delivery as "customer unavailable" before the 5-minute countdown has expired.

Delivery cancellations

Deliveries may be cancelled at any time until the moment they are delivered or in the "Completed" stage. Delivery fees may still apply. You can consult our cancellation fees policy for more information.

Additional Support

If you have any questions regarding the SnapGrab BOOKINGS API, please contact us.

	Single Delivery Same-Day DIRECT	2+ deliveries Same-Day DIRECT	Same-Day Before 10PM Cut-off: 12PM
Base Rate	$ 14.99	$ 12.99	Contact Us
Included FREE KM per Delivery	4 KM	7 KM	N/A
Distance rate for extra KM	$ 1.10	$ 0.85	N/A
Rush hour pick -up charge (4pm - 6pm)	% 30	% 30	N/A
Greater Montréal delivery
	Start Now	Start Now	Contact Us

Single Delivery Same-Day DIRECT
Base Rate	$ 14.99
Included FREE KM per Delivery	4 KM
Distance rate for extra KM	$ 1.10
Rush hour pick -up charge (4pm - 6pm)	% 30
Greater Montréal delivery
Start Now

2+ deliveries Same-Day DIRECT
Base Rate	$ 12.99
Included FREE KM per Delivery	7 KM
Distance rate for extra KM	$ 0.85
Rush hour pick -up charge (4pm - 6pm)	% 30
Greater Montréal delivery
Start Now

Same-Day Before 10PM Cut-off: 12PM
Base Rate	Contact Us
Included FREE KM per Delivery	N/A
Distance rate for extra KM	N/A
Rush hour pick -up charge (4pm - 6pm)	N/A
Greater Montréal delivery
Contact Us

For Developers

For Developers

Introduction

Resources

More

Introduction

Overview

What can the API do?

What do businesses get delivered with the API?

Authentication

Server

Test Mode

Live Key

Versioning

Addresses

Requests

Responses

Error codes

VALIDATION ERRORS

PROCESSING ERRORS

HTTP ERROR CODES

Resources

Getting a Delivery Quote

REQUEST INFORMATION

RESPONSE INFORMATION

ERRORS

Creating a Delivery

REQUEST INFORMATION

RESPONSE INFORMATION

ERRORS

Track an order

REQUEST INFORMATION

RESPONSE INFORMATION

ERRORS

Cancelling an order

REQUEST INFORMATION

RESPONSE INFORMATION

ERRORS

List Orders

REQUEST INFORMATION

RESPONSE INFORMATION

ERRORS

More

Customer unavailable at delivery

Delivery cancellations

Additional Support

SNAPGRAB

MERCHANTS

FLEET

Follow Us