API

Shurpa provides best-in-class delivery services for a wide variety of merchants. You can learn more about us and what we do on our homepage.

This API is used to send us information about deliveries as orders come in, as well as to keep merchants up to date as deliveries are completed. Sign up is currently not available to the public, so please contact info@shurpa.com if you're interested in using our services.

Data Transport

The API sends and receives UTF-8 encoded JSON data via REST actions over SSL. To conform with this, please ensure that you include a Content-Type: application/json header with all requests.

Environments

There are two environments: one for testing and one for production. They are kept completely separate from each other, and require unique accounts for authentication. They use different hosts to maintain this separation.

TEST HOST: https://staging.shurpa.com/
PRODUCTION HOST: https://www.shurpa.com/

The two environments are otherwise identical, so switching between them is as easy as swapping out the host and the authentication token.

Authentication

Authentication happens via a bearer token provided in a header. The header should be called Authorization and the value should be Bearer TOKEN where TOKEN is replaced with your actual token value.

Get Account

Get information for the account associated with the token.

Request

GET /api/v1/me

Response

{
  "name": "Test Client",
  "email": "client@example.com",
  "webhook_url": "https://localhost:2222/webhook",
  "window": "Monday 09:00-17:00"
}

Create Delivery

Create a new delivery.

Request

POST /api/v1/deliveries

{
    "first_name": "Test",
    "last_name": "Testerson",
    "business_name": "Test Business"
    "email": "test@example.com",
    "phone": "8554444444",
    "street": "1338 W Concord Pl",
    "unit": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60642",
    "notes": "",
    "external_id": "",
    "package_count": 1,
    "window": ""
}

first_name and last_name together or business_name is required. You may provide all three.
email and phone are optional, but you should provide them if you can. phone should be a 10 digit string, which we will normalize.
street, city, state, and zip are all required.
unit is optional for the address unit, e.g. "Apartment 3" or "Room 101".
notes is optional for any notes about delivery, e.g. "Please leave at the front door", and is the only field that may include line breaks.
external_id is optional for recording your system's unique ID associated with this delivery.
package_count is optional for specifying the number of physical packages in this delivery (default: 1, max: 5).
window is optional for when a delivery should be made, formatted as "DAY_OF_WEEK HH:MM-HH:MM". DAY_OF_WEEK is optional, but if included it should be the full name of the day. The two times are both required, and the first time must be earlier than the second. For example: "15:00-19:00" or "Monday 9:00-12:00". If a window is not provided then the default for your account is used, which can be seen in the window field of the Get Account endpoint.

Response

Returns the delivery object. See Get Delivery.

Get Delivery

Get a delivery by ID.

Request

GET /api/v1/deliveries/:id

Response

{
  "delivery": {
    "id": "abc123",
    "first_name": "Test",
    "last_name": "Testerson",
    "business_name": "Test Business",
    "email": "test@example.com",
    "phone": "+18554444444",
    "street": "1338 W Concord Pl",
    "unit": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60642",
    "notes": "",
    "external_id": "",
    "package_count": 1,
    "window": "13:00-18:00",
    "status": "received",
    "label_url": "https://www.shurpa.com/api/v1/deliveries/abc123/label.pdf",
    "tracking_url": "https://www.shurpa.com/track?id=abc123",
    "stop_number": 0,
    "route_name": "",
    "pod_description": null,
    "pod_signature": null,
    "pod_url": null
  }
}

stop_number is the stop number for this delivery within a route once one is assigned (default: 0). Please note that this may be the same for multiple deliveries within the same route. Not immediately available and subject to change.
route_name is the name of this delivery's route once one is assigned. Not immediately available and subject to change.

pod_description will only be present and not null if a proof of delivery description was written.
pod_signature is a base64 encoded SVG and will only be present and not null if the recipient signed for the package.
pod_url will only be present and not null if a proof of delivery picture was taken.

Note on Returned URLs

The API provides both a label_url and a tracking_url for you to use or forward on to your own customers. Do NOT attempt to construct these programmatically by generating your own URLs. They are not deterministic, and may change depending on your configuration settings and/or partnerships. Instead, you should always use the URL returned as part of the delivery object.

Furthermore, by default label_url is a protected resource. To access it, you must include the authentication header like you would with any other API request.

Delivery Statuses

A delivery's status will change as it goes through certain events in our system. The initial status is always "received" and the final status is always either "delivered" or "canceled".

Here are all the possible statuses and their definitions:

"received" - the delivery information has been received
"picked_up" - the delivery has been physically picked up
"arrived" - the delivery has arrived at a sorting facility (optional, may repeat)
"departed" - the delivery has departed a sorting facility (optional, may repeat)
"delivered" - the delivery has been successfully delivered
"canceled" - the delivery has been canceled

Webhooks

The webhooks below are POST requests you will receive at the URL you provided during setup. If your server does not respond with a status code of 200 then we will retry up to 3 times. If the last attempt fails we will email you to alert you that there is a problem with your webhook. You can verify the webhook URL and email address used here by checking the webhook_url and email fields returned by the Get Account endpoint.

Picked Up

This webhook is triggered when the package is physically picked up.

The same fields and values as when you GET a delivery will also be here, except that the status field should usually have a value of "picked_up". Note that if events happen quickly it is possible for the delivery's status to have already changed due to the asynchronous nature of webhooks.

Delivered

This webhook is triggered when the package is delivered to the recipient.

The same fields and values as when you GET a delivery will also be here, except that the status field will have a value of "delivered", and you can expect that at least one of pod_description, pod_signature, or pod_url will be present and not null (though it's possible for all three to exist).