Dropbuddies API

Using the Dropbuddies Delivery API, developers can integrate our on-demand local delivery platform into their applications. The API is designed to allow application developers to check prices, schedules, book a delivery, then follow updates on that delivery till completion.

Overview

To get started using the Dropbuddies Delivery API:
Sign up for a Business account.
Locate your appID and secret key in the business app.
Check out a few tutorials on how to use the API: cURL, Dropbuddies.

What can the API do?

You can use the Dropbuddies API to utilize our fleet of couriers to deliver your products within our geographic zones.
Here is the flow of events that developers most commonly follow when using our API:
To see if a delivery is possible, request a delivery quote. This endpoint takes in two addresses and returns a fee, ETA, and other information about a potential delivery.
After you have evaluated whether the quoted price and delivery estimate meets your needs, you can create a delivery.
While a delivery is in progress, you can track its status in real-time in the developer dashboard, by polling the API, or with webhooks.

AUTHENTICATION

The Dropbuddies API requires authentication by HTTP Basic Auth headers. Your API key should be included as the username. The password should be left empty.
The actual header that is used will be a base64-encoded string like this:
Basic Y2YyZjJkNmQtYTMxNC00NGE4LWI2MDAtNTA1M2MwYWYzMTY1Og== Most of the endpoints provided in the Dropbiuddies API are in relation to a specific customer. You'll need to provide your customer id and include it in the URL.

REQUESTS

The base URL for all requests to the Dropbuddies API is:

https://api.dropbuddies.com/

Our API is REST-based. This means:
It makes use of standard HTTP verbs like GET, POST, DELETE.
The API uses standard HTTP error responses to describe errors.
Authentication is specified with HTTP Basic Authentication.
All requests use standard query encoding.
POST data should be encoded as standard application/x-www-form-urlencoded.

Rate Limiting

There is a global rate limit for API requests.

...

Versioning

Versioning allows us to provide developers a consistent experience. We provide two levels of versioning:
Resource: All endpoints are prefixed with a version such as /v1. This version refers to the overall layout of the endpoints and response standards.
Client: Developers can ensure consistent fields and formats by specifying a version as a HTTP header

X-Dropbuddies-Version header such as X-Dropbuddies-Version: 20140825

Addresses

Please format pickup and dropoff addresses this way:

Street Address, City, State, Zip

Any other information, like apartment number, door codes, "care of" instructions, should all be added to pickup or dropoff notes fields. Any extra information included may result in a malformed address, and our geocoder will not be able to find the location.

RESPONSES

The Dropbuddies API uses HTTP status codes to indicate the status of your requests. This includes successful and unsuccessful responses.
All responses are in JSON.

Status Codes

• 200 - OK: Everything went as planned.
• 304 - Not Modified: Resource hasn't been updated since the date provided. See Caching below.
• 400 - Bad Request: You did something wrong. Often a missing argument or parameter.
• 401 - Unauthorized: Authentication was incorrect.
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error: We had a problem processing the request
• 503 - Service Unavailable: Try again later.

Errors

Error responses include details about what went wrong.

{
"error": 200,
"message": "The parameters of your request were invalid."
}

Error Codes

This list will likely become more comprehensive as features are implemented.
• invalid_params - The indicated parameters were missing or invalid.
• unknown_location - We weren't able to understand the provided address. This usually indicates the address is wrong, or perhaps not exact enough.
• rate_limit_exceeded - This API key has made too many requests.
•customer_not_approved - You account has not been approved to create deliveries. Please refer to our approval guidelines for more information.
• account_suspended
• not_found
• service_unavailable
• delivery_limit_exceeded - You have hit the maximum amount of ongoing deliveries allowed.
• customer_limited - Your account's limits have been exceeded.
• couriers_busy - All of our couriers are currently busy.

Types

Responses often indicate a type of object being described. Though this can often be inferred from the resource being requested, but we like to be explicit:

{
	kind: "user",
	name: "Kunle"
}
							

Some responses might include a list of objects:

{
  kind: "list",
  data: [
    {
      kind: "user",
      name: "Kunle"
    },
    {
      kind: "user",
      name: "Ciroma"
	}
  ]
}
							

Currency

When a response involves a currency, it is described as follows:

{
  amount: 1000,
  currency: "NGN"
}
							

This indicates a value of N1000 in NGN.

Times

Times are formatted according to ISO8601 and reported only in UTC time. For example:

{
  created: "2014-08-26T10:04:03Z",
}
							

Objects will often have attributes like "created" and "updated".

Locations

Some objects have a geographic location associated with them. This typically of the form:

{
  "location" : {
    "latitude" : 37.42291810,
    "longitude" : -122.08542120
  }
}
                        

If you want to play around with our endpoints, you can use Dropbuddies:

Events

The delivery create API endpoint has optional post parameters for specifying when various delivery events occur.
pickup - When Robo will start moving towards the pickup
pickup_complete - When Robo will have picked up the items.
dropoff - When Robo will start moving towards the dropoff.
delivered - When Robo will complete the delivery.

Post Example

Here is an example where Robo will start pickup in 10 minutes, pickup_complete in 20 minutes, dropoff in 21 minutes and delivered in 34 minutes.

POST
/api/orders/history
{
	"error": 200,
	"message": "string",
	"data": [
	  {
        "id": 0,
		"unique_id": "string",
		"pickup_address": "string",
		"dropoff_address": "string",
		"pickup_location": {
		  "address": "string",
		  "geocode": "string",
		  "longitude": 0,
		  "latitude": 0,
		  "isOnline": 0,
		  "type": "string"
		},
		"dropoff_location": {
		  "address": "string",
		  "geocode": "string",
		  "longitude": 0,
		  "latitude": 0,
		  "isOnline": 0,
		  "type": "string"
		},
		"item_type": "string",
		"description": "string",
		"size_fit": "string",
		"request_type": "string",
		"delivery_type": "string",
		"ownerid": "string",
		"owner_type": "string",
		"pickup_name": "string",
		"pickup_phonenumber": "string",
		"pickup_email": "string",
		"recipient_name": "string",
		"recipient_phonenumber": "string",
		"recipient_email": "string",
		"source": "string",
		"payment_status": "string",
		"delivery_status": "string",
		"status": "string",
		"user_delivery_status": "string",
		"rating_message": "string",
		"dropbuddy_id": "string",
		"promo_code": "string",
		"value_of_item": 0,
		"rating": 0,
		"dropoff_time": 0,
		"pickup_time": 0,
		"pickup_longitude": 0,
		"pickup_latitude": 0,
		"created_on": 0,
		"updated_on": 0,
		"accepted_on": 0,
		"selectDropBuddy": 0,
		"allowPriceSuggestion": 0,
		"cancelled_on": 0,
		"quantity": 0,
		"suggestedPrice": 0
	  }
	]
}
							

Pathing

Pathing on Robo is as the crow flies between its location and either its pickup or dropoff point depending on the job state. The rate in which Robo moves is based on the when the next event occurs. For example, if pickup is at 00:00:00 and pickup_complete is at 00:10:00 then the rate is the distance between Robo's current location divided by 10 minutes.

Invalid Event Configurations

Delivery states happen in order so if the event configuration does not respect this order then the event configuration is ignored.

How do I get a production key?

When you're ready to start doing live deliveries, update your payment details and use your production API key.

Endpoints

GET AN ESTIMATE

The first step in using the Dropbuddies API is get a quote on a delivery. This allows you to make decisions about the appropriate cost and availability for using the Dropbuddies platform, which can vary based on distance and demand.
A Delivery Quote provides an estimate for a potential delivery. This includes the amount the delivery is expected to cost as well as an estimated delivery window. As demand on our platform changes over time, the fee amount and ETA may increase beyond what your use-case can support.
A Delivery Quote can only be used once and is only valid for a limited duration.

Endpoint

POST - /api/orders/estimate

Query Parameters

Name Description
pickup_location (required in place of pickup_address) The pickup location for a potential delivery.
Example
"pickup_location": {
  "longitude": 0,
  "latitude": 0
}
                                    
dropoff_location (required in place of dropoff_address) The dropoff location for a potential delivery.
Example
"dropoff_location": {
  "longitude": 0,
  "latitude": 0
}
                                    
pickup_address The pickup location for a potential delivery.
Example
"pickup_address": "18 Rainbow Drive, Allen, Ikeja, Nigeria"
dropoff_address The dropoff location for a potential delivery.
Example
"dropoff_address": "18 Rainbow Drive, Allen, Ikeja, Nigeria"
delivery_type You can set the delivery type of your request based on the level of urgency.
DELIVERY TYPES

REGULAR - Get your items delivered the same day the request is made

NEXTDAY - Get your items 24-48hours after request is made

Example - "|" is or
"delivery_type": "REGULAR|NEXTDAY"
request_type
DELIVERY TYPES

REGULAR - Get your items delivered the same day the request is made

NEXTDAY - Get your items 24-48hours after request is made

Example - "|" is or
"request_type": "DISPATCH"
size_fit Specify what is most suitable for transporting the item
SIZE-FITS

CAR - Fits in a car

BIKE - Fits in a bike

BAG - Fits in a bag

"request_type": "CAR"

Response

{
  "error": 200,
  "message": "string",
  "data": {
    "dropoff_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0
    },
    "pickup_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0
    },
    "totalDistance": 0,
    "totalDuration": 0,
    "totalFare": 0,
    "duration": 0,
    "realCost": 0,
    "totalPayment": 0,
    "service_fee": 0
  }
}

CREATE A DELIVERY

After you've successfully created a delivery quote, it's time to create an actual delivery on the Dropbuddies platform. It's recommended that you include the previously generated quote_id to ensure the costs and ETAs are consistent with the quote. Once a delivery is accepted, the delivery fee will be deducted from your account.

Endpoint

POST - /api/orders/place/dispatch

Query Parameters

Name Description
pickup_location (required in place of pickup_address) The pickup location for a potential delivery.
Example
"pickup_location": {
  "longitude": 0,
  "latitude": 0
}
                                    
dropoff_location (required in place of dropoff_address) The dropoff location for a potential delivery.
Example
"dropoff_location": {
  "longitude": 0,
  "latitude": 0
}
                                    
pickup_address The pickup location for a potential delivery.
Example
"pickup_address": "18 Rainbow Drive, Allen, Ikeja, Nigeria"
dropoff_address The dropoff location for a potential delivery.
Example
"dropoff_address": "18 Rainbow Drive, Allen, Ikeja, Nigeria"
pickup_name (required) Set Pickup name
Example
"pickup_name":""
pickup_phonenumber (required) Set Pickup phonenumber
Example
"pickup_phonenumber":""
pickup_email Set Pickup email
Example
"pickup_email":""
recipient_name (required) Set Recipient name
Example
"recipient_name":""
recipient_phonenumber (required) Set Recipient phonenumber
Example
"recipient_phonenumber":""
recipient_email Set Recipient email
Example
"recipient_email":""
delivery_type You can set the delivery type of your request based on the level of urgency.
DELIVERY TYPES

REGULAR - Get your items delivered the same day the request is made

NEXTDAY - Get your items 24-48hours after request is made

Example - "|" is or
"delivery_type": "REGULAR|NEXTDAY"
request_type
DELIVERY TYPES

REGULAR - Get your items delivered the same day the request is made

NEXTDAY - Get your items 24-48hours after request is made

Example - "|" is or
"request_type": "DISPATCH"
size_fit Specify what is most suitable for transporting the item
SIZE-FITS

CAR - Fits in a car

BIKE - Fits in a bike

BAG - Fits in a bag

"request_type": "CAR"
description An overall detail about the delivery
"description": ""
value_of_item The actual value of item in Naira
"value_of_item": 0.00
pickup_time You can specify when you'd want the delivery to be picked up
"pickup_time": 152037089238(future timestamp in millis)
dropoff_time You can specify when you'd want delivery to be done
"dropoff_time": 152037089238(future timestamp in millis)

Response

{
  "order": {
    "unique_id": "string",
    "pickup_address": "string",
    "dropoff_address": "string",
    "pickup_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0,
      "isOnline": 0,
      "type": "string"
    },
    "dropoff_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0,
      "isOnline": 0,
      "type": "string"
    },
    "item_type": "string",
    "description": "string",
    "size_fit": "string",
    "request_type": "string",
    "delivery_type": "string",
    "ownerid": "string",
    "owner_type": "string",
    "pickup_name": "string",
    "pickup_phonenumber": "string",
    "pickup_email": "string",
    "recipient_name": "string",
    "recipient_phonenumber": "string",
    "recipient_email": "string",
    "source": "string",
    "payment_status": "string",
    "delivery_status": "string",
    "status": "string",
    "user_delivery_status": "string",
    "rating_message": "string",
    "dropbuddy_id": "string",
    "promo_code": "string",
    "value_of_item": 0,
    "rating": 0,
    "dropoff_time": 0,
    "pickup_time": 0,
    "pickup_longitude": 0,
    "pickup_latitude": 0,
    "id": 0,
    "created_on": 0,
    "updated_on": 0,
    "accepted_on": 0,

    "cancelled_on": 0,
    "quantity": 0,

  },
  "payment": {
    "id": 0,
    "created_on": 0,
    "updated_on": 0,
    "completed_on": 0,
    "total_payment": 0,
    "real_cost": 0,
    "has_promo": 0,
    "transaction_id": "string",
    "reference": "string",
    "payment_handler": "string",
    "ownerid": "string",
    "owner_type": "string",
    "user_identifier": "string",
    "user_type": "string",
    "payment_method": "string",
    "description": "string",
    "currency": "string",
    "promo_code": "string",
    "promo_object": {
      "id": 0,
      "created_on": 0,
      "updated_on": 0,
      "expires_on": 0,
      "total_available": 0,
      "total_consumed": 0,
      "promo_code": "string",
      "ownerid": "string",
      "owner_type": "string",
      "state": "string",
      "value": "string",
      "value_type": "string",
      "type": "string",
      "newUsersOnly": 0
    }
  }
}
                        

LIST DELIVERIES

List all deliveries for a customer

Endpoint

GET - /api/orders/history

Query Parameters

Name Description
mode=DESC|ASC (query) Order requests by descending or ascending order
limit=50 (query) Order requests by descending or ascending order
orderby=any of the order parameters (query) Order requests by descending or ascending order
status=PENDING|COMPLETED
Allows | as or.. Therefore PENDING or COMPLETED requests
You can filter result to requests within the parameters

Response

{
    "error": 200,
    "message": "string",
    "data": [
      {
        "id": 0,
        "unique_id": "string",
        "pickup_address": "string",
        "dropoff_address": "string",
        "pickup_location": {
          "address": "string",
          "geocode": "string",
          "longitude": 0,
          "latitude": 0,
          "isOnline": 0,
          "type": "string"
        },
        "dropoff_location": {
          "address": "string",
          "geocode": "string",
          "longitude": 0,
          "latitude": 0,
          "isOnline": 0,
          "type": "string"
        },
        "item_type": "string",
        "description": "string",
        "size_fit": "string",
        "request_type": "string",
        "delivery_type": "string",
        "ownerid": "string",
        "owner_type": "string",
        "pickup_name": "string",
        "pickup_phonenumber": "string",
        "pickup_email": "string",
        "recipient_name": "string",
        "recipient_phonenumber": "string",
        "recipient_email": "string",
        "source": "string",
        "payment_status": "string",
        "delivery_status": "string",
        "status": "string",
        "user_delivery_status": "string",
        "rating_message": "string",
        "dropbuddy_id": "string",
        "promo_code": "string",
        "value_of_item": 0,
        "rating": 0,
        "dropoff_time": 0,
        "pickup_time": 0,
        "pickup_longitude": 0,
        "pickup_latitude": 0,
        "created_on": 0,
        "updated_on": 0,
        "accepted_on": 0,
        "selectDropBuddy": 0,
        "allowPriceSuggestion": 0,
        "cancelled_on": 0,
        "quantity": 0,
    
      }
    ]
}

GET A DELIVERY

Retrieve updated details about a delivery.

Endpoint

GET /api/orders/:order_id

Response

{
  "error": 200,
  "message": "string",
  "data": {
    "unique_id": "string",
    "pickup_address": "string",
    "dropoff_address": "string",
    "pickup_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0,
      "isOnline": 0,
      "type": "string"
    },
    "dropoff_location": {
      "address": "string",
      "geocode": "string",
      "longitude": 0,
      "latitude": 0,
      "isOnline": 0,
      "type": "string"
    },
    "item_type": "string",
    "description": "string",
    "size_fit": "string",
    "request_type": "string",
    "delivery_type": "string",
    "ownerid": "string",
    "owner_type": "string",
    "pickup_name": "string",
    "pickup_phonenumber": "string",
    "pickup_email": "string",
    "recipient_name": "string",
    "recipient_phonenumber": "string",
    "recipient_email": "string",
    "source": "string",
    "payment_status": "string",
    "delivery_status": "string",
    "status": "string",
    "user_delivery_status": "string",
    "rating_message": "string",
    "dropbuddy_id": "string",
    "promo_code": "string",
    "value_of_item": 0,
    "rating": 0,
    "dropoff_time": 0,
    "pickup_time": 0,
    "pickup_longitude": 0,
    "pickup_latitude": 0,
    "id": 0,
    "created_on": 0,
    "updated_on": 0,
    "accepted_on": 0,
    "cancelled_on": 0,
    "quantity": 0
  }
}

CANCEL A DELIVERY

Cancel an ongoing delivery. A delivery can only be canceled prior to a courier completing pickup. Delivery fees still apply.

Endpoint

POST POST /api/orders/cancel/:order_id

Response

{
  "error": 200,
  "message": "Order cancelled"
}
                        

Resources

CLIENT LIBRARIES

Below you'll find a list of client libraries contributed by our developers. If you've written a library and want to share it with us, please tweet at us @Dropbuddies

Java

• Java by dropbuddies

Javascript

• Javascript by dropbuddies

PHP

• dropbuddies-api by dropbuddies
• dropbuddies-client by dropbuddies

Android

• dropbuddies-android by dropbuddies

SHOPPING CART PLUGINS

If you have built a shopping cart plugin and want to share it with us please tweet at us @Dropbuddies

APPROVAL GUIDELINES

Once you’ve registered for a developer account, you’ll be put into a queue to be considered for a production API key. Below you’ll find some guidelines for getting approved.
• Provide accurate app name and contact information.
• Provide detailed description of what you’re building.
• Supply estimated delivery volume and markets.
• Provide valid payment information.

Here are some good use cases for the API:
• Retail brands with local inventory.
• Food brands who want to create deliveries from their web and mobile properties.

You will most likely not be approved for a production key in these scenarios:
• You need the courier to purchase the items, rather than just fulfill the delivery.
• You’re building a copy of or competitor to Dropbuddies.
• Your use case violates our Terms of Use

API BRAND GUIDELINES

Thank you for integrating Dropbuddies into your app! We created this document to help communicate our branding guidelines to API partners.

Download the Dropbuddies API Design Guidelines.
Any questions? Shoot a mail to developers@dropbuddies.com.