Overview

Doorbound’s RESTful API allows users to offer same-day delivery from their eCommerce websites. The API is implemented as JSON over HTTP using all four verbs (GET/POST/PUT/DELETE). Each resource has its own URL.

Authentication

Companies

Deliveries

Locations


Authentication

[+] Authenticate your request

Some API calls do not require authentication (eg get a list of all company locations). You may safely perform these calls client-side, using AJAX.


When the API call requires authentication, you must include the following header along with your HTTP request:

Authorization: Token token=”#{your_api_key}”

API calls that require authentication must be performed server-side. If a third party gains access to your API key, they’ll be able to impersonate you.

You can find #{your_api_key} under your account's API section.


Companies

[+] Check whether your company delivers to a given address

You can adjust the delivery radius for each of your locations on your admin panel. For the GET request below, you’ll need #{your_company_id}, located under your account's API section.

Authentication required: NO

URL query parameters
  • zip − (required) the delivery location's zip code

URL
GET /api/v1/companies/#{your_company_id}/delivers_to
Response
HTTP/1.1 200 OK

{ “delivery”: true }

Deliveries

[+] Create delivery quotes

When you request delivery quotes, we’ll create an array of deliveries, each corresponding to a different service option. Your company will not be charged (and no driver will be dispatched) until you place a delivery by confirming one of those options.

Authentication required: YES

Request attributes
  • pieces − (required) total number of pieces.
  • weight − (required) cumulative weight of all pieces, in pounds.
  • scheduled_window_start − (optional) include this field if you want to get a quote for a Scheduled delivery. You can see the Scheduled delivery service description at https://doorbound.com/store/deliveries/new. If you’re including this field, please use ISO 8601 date and time format.
  • order_id − (optional) store's order ID that the driver can use for reference.
  • company_location_id − (optional) if you omit this field, we’ll automatically select the company location closest to the customer’s address. Otherwise, if you want to specify a location, you can reference its ID here (see getting a list of all company locations ).
  • pick_up_from_customer − (optional; default: false) whether to pick up the items from the customer’s location and deliver to the store.
  • pick_up_instructions − (optional) instructions the driver should follow at the pick-up location.
  • drop_off_instructions − (optional) instructions the driver should follow at the drop-off location.
  • customer
    • name − (required)
    • phone − (required)
    • email − (optional)
    • location
      • street1 − (required)
      • street2 − (optional)
      • city − (required)
      • state − (required)
      • zip − (required)
      • country − (required)

URL
POST /api/v1/deliveries

Example request
{
  “delivery”: {
    “pieces”: 2,
    “weight”: 30,
    “scheduled_window_start”: “2013-08-14T15:30:00-0700”,
    “order_id”: “54AB9”,
    “company_location_id”: 34,
    “pick_up_instructions”: “Get items from Jill at the front counter”,
    “drop_off_instructions”: “OK to leave at door”,
    “customer”: {
      “name”: “Eric Theodore Cartman”,
      “phone”: “333 333 4444”,
      “email”: “eric.cartman@southparkstudios.com”,
      “location”: {
        “street1”: “21208 E. Bonaza Cir.”,
        “street2”: “Suite 45”,
        “city”: “South Park”,
        “state”: “CO”,
        “zip”: “80440”,
        “country”: “USA”
      }
    }
  }
}

Example response
HTTP/1.1 201 Created

{
  “delivery_options”: [
    {
      “service_type”: “hotshot”,
      “service_description”: “Delivery within 1 hour.”,
      “delivery_id”: 207,
      “delivery_total”: “19.99”
    },
    {
      “service_type”: “rush”,
      “service_description”: “Delivery within 4 hours.”,
      “delivery_id”: 208,
      “delivery_total”: “14.99”
    },
    {
      “service_type”: “same_day”,
      “service_description”: “Delivery by 5pm for orders placed by noon. For orders placed in the afternoon, delivery by 5pm next day.”,
      “delivery_id”: 209,
      “delivery_total”: “9.99”
    },
    {
      “service_type”: “scheduled”,
      “service_description”: “Delivery within a scheduled 1-hour time window.”,
      “delivery_id”: 210,
      “delivery_total”: “14.99”
    }
  ]
}
[+] Place a delivery

Before placing a delivery, you’ll need to create delivery quotes. Creating delivery quotes will return a list of delivery options.

You place a delivery by confirming a delivery option. After successfully confirming, your company will be charged and a driver will be assigned to the job.

Note that when you place a delivery, the request isn’t guaranteed to succeed. Since driver availability changes constantly, delivery quotes may expire over time. So by the time you place a delivery, that delivery option's quote may have expired.

The time horizon for quote expirations varies by delivery service type. 1-hour service quotes may expire after a few minutes, while same-day delivery quotes may not expire for several hours.

You should always check the server’s response to your request. If you receive an error message stating that your delivery quote expired, you can always try creating new quotes.

Authentication required: YES

URL query parameters
  • test − (optional; default: false) when set to true, no driver will be assigned to the job, your company will not be charged, and the delivery option will remain unconfirmed. You’ll receive a successful server response so long as the #{delivery_id} exists and the quote hasn’t expired.

URL
PUT /api/v1/deliveries/#{delivery_id}/confirm
Example success response
HTTP/1.1 204 No Content
Example error response
HTTP/1.1 409 Conflict

{ “errors”: { “quote”: [“is outdated. Please try gathering a new quote.”] } }
[+] Receive a single delivery
Authentication required: YES

URL
GET /api/v1/deliveries/#{delivery_id}
Response
HTTP/1.1 200 OK

{
  “delivery": {
    “id”: 207,
    “pieces”: 2,
    “weight”: 30,
    “order_id”: “54AB9”,
    “pick_up_instructions”: “Get items from Jill at the front counter”,
    “drop_off_instructions”: “OK to leave at door”,
    “service_type”: “hotshot”,
    “service_description”: “Delivery within 1 hour.”,
    “placed_at”: “2012-12-26T21:36:12-08:00”,
    “collected_at”: null,
    “delivered_at”: null,
    “pick_up_from_customer”: false,
    “company_location”: {
      “id”: 34,
      “name”: “My Costume Store - East”,
      “phone”: “1234567890”,
      “delivery_radius”: 15,
      “street1”: “1002 Bogus Drive”,
      “street2”: null,
      “city”: “South Park”,
      “state”: “CO”,
      “zip”: “80445”,
      “country”: “USA”
    },
    “customer”: {
      “name”: “Eric Theodore Cartman”,
      “phone”: “3333334444”,
      “email”: “eric.cartman@southparkstudios.com”,
      “location”: {
        “street1”: “21208 E. Bonaza Cir.”,
        “street2”: “Suite 45”,
        “city”: “South Park”,
        “state”: “CO”,
        “zip”: “80440”,
        “country”: “USA”
      }
    }
  }
}

Locations

[+] Get a list of all company locations

For the GET request below, you’ll need #{your_company_id}, located under your account's API section.

Authentication required: NO

URL
GET /api/v1/companies/#{your_company_id}/locations
Response
HTTP/1.1 200 OK

{
  "locations”: [
    {
      “id”: 46,
      “name”: “Example Store - Bellevue”,
      “phone”: “1234567890”,
      “delivery_radius”: 15,
      “latitude”: null,
      “longitude”: null,
      “street1”: “700 Bellevue Way Northeast #120”,
      “street2”: “”,
      “city”: “Bellevue”,
      “state”: “WA”,
      “zip”: “98006”,
      “country”: “USA”
    },
    {
      “id”: 18,
      “name”: “Example Store - Seattle”,
      “phone”: “1234567890”,
      “delivery_radius”: 15,
      “latitude”: 47.55133,
      “longitude”: -122.11288,
      “street1”: “263 Yale Avenue North”,
      “street2”: “”,
      “city”: “Seattle”,
      “state”: “WA”,
      “zip”: “98102”,
      “country”: “USA”
    }
  ]
}