SnapGrab Icon

For Developers

Introduction

Overview

To get started using the SnapGrab API:

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 CodeMessageFix
101DropOff address is not located in serviced delivery areaThis address cannot be delivered to. Check out our delivery zone.
102Delivery has been scheduled for more than 7 days into the futureYou cannot scheduled a delivery for more than 7 days into the future. Select a closer delivery date and time.
103Delivery should be scheduled at a minimum of 5 minutes into the futureThe scheduled delivery time must be at least 5 minutes into the future. Select a later date and time.
104DropOff time is not within SnapGrab's operating timesSnapGrab operates between 10AM and 10PM. Select a schedule delivery time between these times.
105Invalid DropOff address format, must be a Google recognized formatPlease follow Google maps address format.
106Missing information fields, DropOff customer name should be a minimum of 2 characters longThe customer name must be at least 2 characters. Please review the name.
107Missing informations fields, the DropOff phone number is invalidThe customer's phone number should be 10 digits long.
108Invalid Information fields. Instructions should be less than 65 characters.The instructions are too long. Please limit the value to less than 65 characters.
109User does not have a valid payment method on file.Please add a valid payment card in your merchant account dashboard.
110Invalid param "Param_name"Please review your parameters.
PROCESSING ERRORS
Error CodeMessageFix
201Your Merchant payment card was declinedPlease use a valid payment method in your Merchant account dashboard.
202Token is not valid or is deprecatedRequest a new token through /order/prepare
203Order is not foundThe order number is incorrect
204Order is already cancelledThis order is already in the cancelled stage
205Order cannot be cancelled anymoreThe 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 ParametersREQUEST INFORMATIONRequired
KeyString - Your unique identifier keyYes
ScheduledAtString - 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
DropOffAddressString.- The drop-off address for a potential delivery in a Google maps understandable formatYes
CustomerNameString - The drop-off recipient's full nameYes
CustomerPhoneString - The 10 digit drop-off recipient's contact phone numberYes
CustomerEmailString - The drop-off recipient's emailYes
InstructionsREQUEST INFORMATIONREQUEST INFORMATION
LargeOrderBoolean - Indicate if the delivery contain large itemNo
BringBackBoolean - Indicate if delivery driver must return items from the drop-off address back to your pick-up locationNo
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 ParametersDescription
TokenString - Your delivery quote token
BaseFareNumber - The base fare of your delivery quote
DistanceFareNumber - The fare for distance charges
LargeOrderFareNumber - The fare for a large order
SurgeTimeBoolean - Surge times are for period of high order volume and may increase the base fare for a delivery
tvqNumber - Local Québec sales tax
tpsNumber - Federal sales tax
TotalAmountNumber - The total amount including all taxes
DeliveryChargeNumber - the fare including the base fare, distance fare and surge time fare.
DistanceNumber - The distance from pickup to drop-off in meters.
ServiceFeeThe service fee fare (if applicable)
ERRORS
Error codeDescription
101The drop-off address is not within SnapGrab's serviced delivery zone
102The scheduled start time must be less than 7 days in the future.
103The scheduled start time must be more than 5 minutes in the future.
104The drop-off time must be between 10:00 EST and 22:00 EST
105The drop-off address is not recognized by us. Please use a Google formatted address.
106Missing information field. Drop-off name must be equal or greater than 2 characters.
107Missing information field. Drop-off phone number is invalid. Drop-off phone number is 10 digits.
108Missing information field. No instruction was given.
109Merchant does not have a valid payment card on file in their account.
110Invalid 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 ParametersDescriptionRequired
KeyString - Your unique identifier keyYes
TokenString - Your delivery quote tokenYes
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 ParametersDescription
IdString - Your delivery order number
TrackingLinkString - The tracking link for real time GPS order tracking
CustomerNameString - The drop-off recipient's full name
DeliveryAddressString.- The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhoneString - The 10 digit drop-off recipient's contact phone number
InstructionsString - Any other important information such as apartment number or buzzer code
ScheduledTimeString - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStageString - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverNameString - The name of the driver executing this delivery.
ERRORS
Error codeDescription
201The merchant's payment card was declined.
202The 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 ParametersDescriptionRequired
KeyString - Your unique identifier keyYes
IdString - Your delivery order numberYes
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 ParametersDescription
IdString - Your delivery order number
TrackingLinkString - The tracking link for real time GPS order tracking
CustomerNameString - The drop-off recipient's full name
DeliveryAddressString.- The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhoneString - The 10 digit drop-off recipient's contact phone number
InstructionsString - Any other important information such as apartment number or buzzer code
ScheduledTimeString - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStageString - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverNameString - The name of the driver executing this delivery.
ERRORS
Error codeDescription
203Order 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 ParametersDescriptionRequired
KeyString - Your unique identifier keyYes
IdString - Your unique identifier for the deliveryYes
ReasonString - The reason why the order is being cancelledNo
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 ParametersDescription
IdString - Your delivery order number
TrackingLinkString - The tracking link for real time GPS order tracking
CustomerNameString - The drop-off recipient's full name
DeliveryAddressString - The drop-off address for a potential delivery in a Google maps understandable format
CustomerPhoneString - The 10 digit drop-off recipient's contact phone number
InstructionsString - Any other important information such as apartment number or buzzer code
ScheduledTimeString - The time you want the delivery to start at. ISO format. Must be less than 7 days in the future.
DeliveryStageString - The stage at which your delivery is in. Received, Accepted, OnWay, Completed or Cancelled.
DriverNameString - The name of the driver executing this delivery.
ERRORS
Error codeDescription
203Order not found - Your order number might be incorrect
204Oder is already in the cancelled stage
205Order 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 ParametersDescriptionRequired
KeyString - Your unique identifier key Yes
OffsetNumber - 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: 0No
LimitNumber - The total number of row (orders) you want returned. Maximum:20. Default:20.No
DeliveryStageArray - If present only deliveries in specified stages will be returned. Accepted values are: "Received", "Accepted", "OnWay", "Completed", "Cancelled". Default is AllNo
SortByString - Determines the field for sorting. Accepted values are: "Id" or "ScheduledAt". Default: "Id".No
OrderByString - Determines the sorting order for the list. Accepted values are: "Asc" or "Desc". Default: "Desc".No
PeriodArray - 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
OrderTypeArray - If present only orders of specified type will be returned. Accepted values are: "Booking", "Menu", "Trip". Default: AllNo
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 ParametersDescription
CountNumber - The total number of order matching the criteria
OrdersString - Array of orders. Order format is the same as /order/track endpoint.
ERRORS
Error codeDescription
110Invalid Parameters. "Param_name".

More

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.