#postmates api

Postmates offered a $5,000 prize to the team who built the best app on the Postmates API, and we saw 38 teams integrate applications with Postmates in a matter of days. We were blown away by the creativity and innovation exhibited by these hackers, and we’re excited to share some of the ideas from the hackathon to inspire future apps to be built on our API.

Helix was an app that brings your doctor to your doorstep (so to speak). Using the Postmates API, they made it possible to get your prescriptions delivered on-demand. NeedATampon? was a crowdsourced app to deliver you a tampon from the nearest publicly available and free stash. We saw some charitable hacks as well -- Salvage brought leftover food from university dining halls to local food banks and Helping Hand delivered food and care packages from generous citizens to the homeless.

There were so many awesome hacks, but in the end we had to pick one winner and we chose Free for Fee. They built a way to get any of the free items advertised on Craigslist delivered to you on-demand for just the price of the Postmates delivery fee. The idea was pretty simple but incredibly useful -- how many times have you wanted something from the free section on Craigslist but didn’t want to go pick it up? Exactly!

Our initial partners for the API launch include Everlane, Curbside, MeUndies, L., Threadflip and Betabrand, with many more to be announced in the coming weeks. All of our partners are using the Postmates API to solve individual logistical challenges.

Everlane has created an entirely new shopping experience called Everlane Now, offering access to basic items in New York and San Francisco within minutes and with great success. Threadflip is using Postmates to have clothing delivered from their sellers to their fulfillment center, while Curbside is extending their existing local pick-up business with an option to have shopping items from partners such as Target delivered on the same day.

POWERING LOCAL COMMERCE

Since the launch of Postmates over two years ago, it has been our vision to provide a reliable infrastructure for on-demand deliveries in every major metropolitan area in the world. And while we stayed focused on food delivery as a vehicle for growth, we've always been fascinated by how our customers use Postmates to hack their cities. We’re hackers ourselves, so observing the ways in which other people hacked our product gave us great satisfaction and added to the belief that cities would benefit from an open delivery infrastructure.

By default, Postmates was designed to be open and without strict categories. The idea that you can enter any store or address, specify an item and have it not only delivered but also purchased at the pick-up allowed our customers to tailor Postmates to their needs and to come up with creative ideas for applying Postmates to their businesses.

One of the early use cases we discovered -- and one that we were most surprised by -- was presented by local bike shop Mission Bicycle. They started using Postmates to deliver bike frames to and from their paint shop in South San Francisco, many times a week. As a result, Mission Bicycle was able enhance their supply chain -- an otherwise costly and staff-intensive project -- with the touch of a button. They were clearly onto something.

CALLING STARTUPS & PARTNERS

Having just completed over 1 million deliveries and learning a lot from our early partners, we believe that this is the right time to invite developers to build on top of the Postmates platform. Not only because we have much greater capacity to handle additional demand, but also because there are too many good ideas out there that require an infrastructure like Postmates. We simply can't build them all ourselves, but others may find it useful to have access to both our infrastructure and our fleet, on top of which they can build their apps.

We hope that many of you will use our API to connect your city in new and exciting ways. We challenge you to provide local retail with a way to compete with Amazon, to design services that offer catering and delivery to hospitalized individuals, and to change the way that we shop for groceries and produce.

Amazon would not have been possible without Fedex or UPS. Imagine what can be built on top of Postmates.

Visit the Developer Site to learn more.

To give you an idea of what's possible with this new API, we're going to walk you through a very simple imaginary application. If you want to skip ahead, go ahead and jump to our developer site and get signed up: https://postmates.com/developer

Let's imagine you want to build a web application called 'Puppies On-Demand'. No, of course you can't use Postmates to send live animals around the city, but you can send stuffed animals.

Customers are going to come to your website, select a stuffed animal puppy from your inventory, fill out their payment information and enter a delivery address. Even before you accept their order, you’ll want to start using our API.

After you've signed up with our developer program, you'll be given two important pieces of information:

1. Customer ID: cus_abc123 2. API Key: fake-api-token-4-u

You'll use both of these to construct HTTP requests to interact with our API.

The first thing you'll want to do for your customer above is verify that we can do the delivery. To get a Delivery Quote, you'll simply provide the pickup and dropoff addresses to our API:

curl -u fake-api-token-4-u: \ -d "dropoff_address=20 McAllister St, San Francisco, CA 94102" \ -d "pickup_address=101 Market St, San Francisco, CA 94105" \ -X POST https://api.postmates.com/v1/customers/cus_abc123/delivery_quotes

You'll get a reply, formatted in JSON:

{ kind: "delivery_quote", id: "dqt_K7SCxZJzteH9R", created: "2014-12-10T10:04:03Z", expires: "2014-12-10T10:09:03Z", fee: 799, currency: "usd", dropoff_eta: "2014-12-10T11:15:03Z", duration: 60 }

What you're looking for in this response (beyond simply the fact that it succeeded) is the cost and duration. These values will vary depending on the demand our fleet is experiencing.

For our application, there is no price too high and no wait too long for our customers to get a stuffed puppy. So we're going to tell our customers we can deliver them a puppy in 60 minutes for $29.95. Once we've charged our customer's credit card, we can submit the delivery to the Postmates API.

curl -u fake-api-token-4-u: \ -d "manifest=1 Stuffed Puppy" \ -d "pickup_name=Puppies On-Demand" \ -d "pickup_address=101 Market St, San Francisco, CA 94105" \ -d "pickup_phone_number=555-555-5555" \ -d "pickup_notes=Just come inside, give us order #123" \ -d "dropoff_name=Alice Customer" \ -d "dropoff_address=20 McAllister St, San Francisco, CA 94102" \ -d "dropoff_phone_number=415-555-5555" \ -d "quote_id=dqt_K7SCxZJzteH9R-" \ -X POST https://api.postmates.com/v1/customers/cus_abc123/deliveries

You should get a delivery object as a response:

{ "id": "del_K7SD1dUd5aqLU-" "kind": "delivery", "live_mode": false, "status": "pending", "complete": false, "updated": "2014-12-09T19:31:22Z", "fee": 799, "currency": "usd", "quote_id": "dqt_K7SCxZJzteH9R-", "courier": null, "created": "2014-12-09T19:31:22Z", "manifest": { "description": "1 Stuffed Puppy" }, "pickup": { "phone_number": "555-555-5555", "notes": "Just come inside, give us order #123", "location": { "lat": 37.7930812, "lng": -122.395944 }, "name": "Puppies On-Demand", "address": "101 Market Street" }, "dropoff": { "phone_number": "415-555-5555", "notes": "", "location": { "lat": 37.7811372, "lng": -122.4123037 }, "name": "Alice Customer", "address": "20 McAllister Street" }, "dropoff_deadline": "2014-12-09T20:31:22Z", "pickup_eta": null, "dropoff_eta": null, }

As your delivery progresses, you'll want to refresh this information. Maybe you want to provide a real-time display for your customers so they can see the delivery arrive. You'll poll the delivery for updates:

curl -u fake-api-token-4-u: \ https://api.postmates.com/v1/customers/cus_abc123/deliveries/del_K7SD1dUd5aqLU-

Some values you'll want to watch:

status: Will move from "pending" to "pickup", "dropoff" then "delivered"

complete: Will be false as long as there are more updates. Great for looping. 

courier: Will contain the name, image and location of the courier while they are working on the delivery.

pickup_eta/dropoff_eta: Gives an estimate of arriving at the pickup location and dropoff location. You might use this to send notifications to your customer when the courier is arriving, or notifying the warehouse to unlock the door.

That's the Postmates Delivery API. Simple, but oh so powerful. We're excited to see what sorts of creative uses you can come up with - whether it's building great new businesses on top of our world-class logistics platform, or just fun hacks to surprise your friends with stuffed puppies.

Stay tuned for exciting new updates as we continue to expand the API and don't hesitate to share your own ideas for how we can improve.

Visit the Developer Site to learn more.