NAV
json

Shurpa API

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

The Shurpa API is used to send Shurpa information about deliveries as orders come in, as well as for Shurpa 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 Shurpa 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.

Header Value
Authorization Bearer token

Account Information

{
  "name": "Test Client",
  "email": "client@example.com",
  "webhook_url": "http://localhost:2222/webhook"
}

GET https://www.shurpa.com/api/v1/me

Description

Get information for the account associated with the token.

Create Delivery

{
  "delivery": {
    "id": "abc123",
    "first_name": "Test",
    "last_name": "Testerson",
    "email": "test@example.com",
    "phone": "+18554444444",
    "street": "2983 N Lincoln Ave",
    "unit": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60657",
    "notes": "",
    "status": "received",
    "package_count": 1,
    "label_url": "https://www.shurpa.com/api/v1/deliveries/6/label.pdf",
    "tracking_url": "https://www.shurpa.com/track?id=abc123"
  }
}

POST https://www.shurpa.com/api/v1/deliveries

Description

Create a new delivery.

Parameter Description
first_name * recipient first name
last_name * recipient last name
email * recipient email
phone * recipient phone number 10 digit string (we will normalize)
street * recipient street address
unit recipient apartment/suite
city * recipient city
state * recipient state 2 digit string
zip * recipient zip 5 digit string
notes recipient notes
package_count number of physical packages in this delivery (default: 1, max: 5)

* required

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:

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.

Get Delivery

{
  "delivery": {
    "id": "abc123",
    "first_name": "Test",
    "last_name": "Testerson",
    "email": "test@example.com",
    "phone": "+18554444444",
    "street": "2983 N Lincoln Ave",
    "unit": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60657",
    "notes": "",
    "status": "received",
    "package_count": 1,
    "label_url": "https://www.shurpa.com/api/v1/deliveries/6/label.pdf",
    "tracking_url": "https://www.shurpa.com/track?id=abc123",
    "pod_description": null,
    "pod_signature": null,
    "pod_url": null
  }
}

Request

GET https://www.shurpa.com/api/v1/deliveries/:id

Description

Get a delivery by id.
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.

Shurpa Webhooks

Description

The webhooks below are POST requests you will receive
at the webhook_url you provided to Shurpa.
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.

Picked Up

This webhook is triggered when the package is picked up for delivery by the courier.

{
  "delivery": {
    "id": "abc123",
    "status": "picked_up"
  }
}

Delivered

This webhook is triggered when the package is delivered to the recipient.
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.

{
  "delivery": {
    "id": "abc123",
    "status": "delivered",
    "pod_description": "Left the package by the door.",
    "pod_signature": "12345aBcDeFgHiJkLmNoPqRsTuVwXyZ67890",
    "pod_url": "https://app.shurpa.com/delivery/123/pod"
  }
}