Authentication

Before jumping in, it is important to cover the three basic levels of Authentication that delivery.com supports:

Level Authentication Description
Unauthenticated client_id Used for most GET calls such as merchant information, menu items, and general search.
Password Flow oauth token Any POST calls and customer specific calls that require prior authorization.
Trusted Flow oauth token Any calls with credit cards.

Unauthenticated

When you sign up for a new API account, you will immediately be able to make “unauthenticated” calls. Simply append your client_id to the request as such:


https://api.delivery.com/endpoint/?client_id={client_id}

To learn more about Password Flow or Trusted Flow please check out the Authentication Overview page.

Making Requests

  • All unauthenticated API requests (requests without an Authorization header) must include a client_id parameter. You receive a client_id by signing up.
  • All production requests must use SSL.
  • All authenticated API requests must include an access token in the Authorization HTTP header. See Authentication.
Environment URL client_id
Production https://api.delivery.com Your app’s client_id.
Development Sandbox accounts has been deprecated as of 5/17/2016

Here’s an example of a search request (broken up for readability):

https://api.delivery.com/merchant/search/delivery
?client_id=abc123
&address=199 Water St 10038

Handling Responses

Content Types

All responses are JSON, as are some request parameters. We don’t support other content types at this time. For example, a search response might look like this:

{
  "search_address" :  {
        "street"        : "235 Park Ave S",
        "city"          : "New York",
        "state"         : "NY",
  },
  "merchants": [
    {
      "id": "3102",
      "summary": {
        "name": "Azuki Japanese Restaurant",
        "cuisines": [
          "Japanese"
        ],
        "phone": "555-555-5555",
        "description": null,
        "overall_rating": "83",
        "num_ratings": 79,
        "type": "R",
        "notes": null
      },
      "ordering": {
        "delivery_processes_card": true,
        "payment_types": [
          "credit",
          "gift card",
          "campus card",
          "promotions",
          "cash"
        ],
        "is_rds": false,
        "time_needed": "30",
        "specials": [
          "10% Off All Orders Over $35",
          "10% Off All Orders Over $50"
        ],
        "next_order_time": "2013-08-22 23:15:00",
        "minimum": "8.00",
        "is_open": true,
        "delivery_charge": "0.50",
        "delivery_percent": "5.00"
      },
      "location": {
        "distance": "0.0134401220484058",
        "street": "239 PARK S AVE",
        "city": "NEW YORK",
        "state": "NY",
        "zip": "10003",
        "longitude": -73.987846,
        "latitude": 40.737839,
        "landmark": "19th & 20th Street"
      }
    }
  ]
}

HTTP Response Codes

The following HTTP response codes are returned by the API. Usually there is additional info included in the body of the response. See Error Handling below.

HTTP Status Code Reason
200 OK The request succeeded.
400 Bad Request Request was invalid. Check the body for more info.
401 Unauthorized Access Token was invalid or not supplied. See Authentication.
500 System Error There was an internal error.
503 Service Unavailable delivery.com is undergoing maintenance or otherwise unavailable.

Error Responses

All error responses have this structure:

{
    "message": [
        {
            "code" 	: 	"dupe_email",
            "user_msg"	:	"An account already exists for komonster@delivery.com.",
            "dev_msg"	: 	"An account already exists for komonster@delivery.com."
        }
    ],
    "other_data"        :     "..."
}
key description
message An array of error messages
code The error code. Error codes will not change, so you should reference these codes in your logic.
user_msg A description of the error that should be helpful to the user. We highly recommend using our descriptions rather than coming up with your own. These are subject to change and so should not be referenced in your logic.
dev_msg A description of the error that is helpful to the developer. It might include links to documentation or detailed instructions that aren’t suited to the end user.
other_data Some endpoints might send back other data that is useful. Check the documentation for that specific endpoint.

Handling Multiple Addresses

In case of multiple locations found for an address.

Example : 1 Rosedale St, Baltimore, MD, United States

HTTP Status Code : 200 OK

{
  "message": [
    {
      "code": "loc_multiple_possible",
      "user_msg": "Multiple addresses possible.",
      "dev_msg": "Multiple addresses possible."
    }
  ],
  "addresses": [
    {
      "street": "1 N Rosedale St",
      "neighborhood": null,
      "city": "Baltimore",
      "sublocality": null,
      "state": "MD",
      "zip": "21229",
      "latitude": 39.28602,
      "longitude": -76.6689,
      "exactMatch": true,
      "unit": null
    },
    {
      "street": "1 S Rosedale St",
      "neighborhood": null,
      "city": "Baltimore",
      "sublocality": null,
      "state": "MD",
      "zip": "21229",
      "latitude": 39.2858,
      "longitude": -76.66889,
      "exactMatch": true,
      "unit": null
    }
  ]
}