Skip to content

Getting started

Introduction

The Parcel API enables your website or application to offer Parcel’s service to your NYC customers. Integration with our RESTful API is quick and easy. Simply POST us the order details, and we will respond in JSON.

To chat with our team about a delivery partnership, email partnerships@fromparcel.com

Overview

You can easily start offering deliveries with the Parcel API by making the following changes to your application:

  • Check the customer’s ZIP code during checkout.
  • Create an order, and get a Parcel shipping label and tracking link.

Usage

Before starting, there are a few important things you should know:

  • Parcel only delivers to certain ZIP codes in the New York City area for different clients. See ZIP codes.
  • Parcel only delivers on certain days of the week for different clients. See delivery windows.

Feedback & issues

Please send feedback and report issues to partners@fromparcel.com.

Going live

Once you’re ready to go live, please contact us so that we can set up billing and give you your live API key.

API

Endpoint

https://api.fromparcel.com/v1

Basics

  • First, contact us to get your test API key.
  • For security purposes, only requests made over HTTPS will work.
  • Never share or publish your API key. This may be obvious, but sharing your API key enables someone to create fraudulent orders or sabotage existing orders.
  • All data must be sent as JSON with the header Content-Type: application/json.
  • Orders created with your test API key will not be delivered. Please do not send packages to addresses generated with a test API key.

Authentication

All requests must be authenticated via HTTP Basic Auth. Use your API key as the username and leave the password blank.

Errors

HTTP codes
200
OK. Everything worked.
201
Item created successfully.
400
Bad request. Parameter missing or invalid.
401
Unauthorized. No valid API key provided.
402
Request failed. Parameters were valid, but something else went wrong. Happens when you try to update or delete an order that shouldn’t be updated or deleted.
404
Not found.
410
Item deleted.
500
Server error. Something went wrong with our servers.
Attributes
message
Human-readable message describing the error.
params
List of parameters that were involved in the error.

Methods

ZIP codes

Retrieving accepted ZIP codes

Parcel only delivers to certain ZIP codes in New York City. You can fetch a list of accepted ZIP codes to check your customer’s ZIP code and offer schedulable deliveries from Parcel.

Do not directly access this resource in the frontend with JavaScript, as that will expose your API key.

GET /accepted_zips
{
  "zip_codes": [
    "10000",
    "10001",
    "10002",
    "10003",
    ...
  ]
}
Attributes
zip_codes
List of ZIP codes in Parcel’s delivery zone.

Delivery windows

Retrieving delivery days and times

Parcel only delivers on certain days of the week. You can check our typical delivery days and times, as well as holidays when we won’t be delivering.

Do not directly access this resource in the frontend with JavaScript, as that will expose your API key.

GET /delivery_windows
{
  "holidays": [
    {
      "date": "2014-10-31",
      "name": "Halloween"
    },
    {
      "date": "2014-11-27",
      "name": "Thanksgiving"
    },
    {
      "date": "2014-12-25",
      "name": "Christmas"
    },
    {
      "date": "2014-12-31",
      "name": "New Year's Eve"
    }
  ],
  "weekdays": {
    "0": {
      "day": [
        {
          "end_time": "18:00:00",
          "start_time": "09:00:00"
        }
      ],
      "night": [
        {
          "end_time": "20:00:00",
          "start_time": "19:00:00"
        },
        {
          "end_time": "21:00:00",
          "start_time": "20:00:00"
        },
        {
          "end_time": "22:00:00",
          "start_time": "21:00:00"
        },
        {
          "end_time": "23:00:00",
          "start_time": "22:00:00"
        }
      ]
    },
    "1": {
      "day": [
        {
          "end_time": "18:00:00",
          "start_time": "09:00:00"
        }
      ],
      "night": [
        {
          "end_time": "20:00:00",
          "start_time": "19:00:00"
        },
        {
          "end_time": "21:00:00",
          "start_time": "20:00:00"
        },
        {
          "end_time": "22:00:00",
          "start_time": "21:00:00"
        },
        {
          "end_time": "23:00:00",
          "start_time": "22:00:00"
        }
      ]
    },
    ...
  }
}
Attributes
holidays

List of objects detailing non-delivering days.

date
ISO format date string
name
Name of holiday
weekdays

Object with integer keys representing days of the week, where Monday is 0 and Sunday is 6, and object values showing day and/or night windows depending on the partnership.

start_time
Time when delivery window starts in ISO format.
end_time
Time when delivery window ends in ISO format.

Addresses

Validating an address

You may check an address to see if it is deliverable. Invalid addresses return a 400 error. Spelling mistakes and ambiguous data may cause the address to be invalid. We may reject any order that we deem undeliverable.

POST /addresses
Request data:

{
  "address_street": "10 w 10th st",
  "address_zip": "10011"
}

Response:
{
  "address_city": "New York",
  "address_lat": 40.733542,
  "address_lng": -73.996326,
  "address_state": "NY",
  "address_street": "10 W 10th St",
  "address_unit": "",
  "address_zip": "10011"
}
Arguments
address_street
required Valid US street address. Apartment/suite units, company names, etc. should be placed in address_unit
address_unit
optional
address_city
optional
address_state
optional
address_zip
required Five-digit US ZIP code as a string. Must be an accepted ZIP code.

Orders

Creating an order

Separate orders should be created if packages are not shipped together and will arrive on different days.

POST /orders
Request data:
{
  "first_name": "John",
  "last_name": "Smith",
  "phone": "5551234567",
  "address_street": "10 w 10th st",
  "address_zip": "10011",
  "address_info": "buzzer broken. text on arrival",
  "delivery_group": "night",
  "delivery_date": "2015-01-01"
}


Response:
{
    "address_city": "NY",
    "address_info": "buzzer broken. text on arrival",
    "address_lat": 40.733543,
    "address_lng": -73.996323,
    "address_state": "NY",
    "address_street": "10 W 10th St",
    "address_unit": null,
    "address_zip": "10011",
    "completed_at": null,
    "created_at": "2014-12-31T19:33:28-05:00",
    "delivery_date": "2015-01-01",
    "delivery_end_time": null,
    "delivery_start_time": null,
    "email": null,
    "first_name": "John",
    "id": 9818556,
    "label_code": null,
    "label_url": null,
    "last_name": "Smith",
    "package_no": 1,
    "phone": "5551234567",
    "received_packages_at": null,
    "shipping_address": {
        "city": "Brooklyn",
        "state": "NY",
        "street": "48 Grattan St",
        "unit": "#9818556",
        "zip": "11237"
    },
    "sort_code": null,
    "status": "date_chosen",
    "test": false,
    "tracking_url": "https://www.fromparcel.com/tracking/9818556/"
}
Arguments
first_name
optional
last_name
optional
email
optional
phone
required Ten-digit US mobile phone number as a string. Used for scheduling deliveries via text message.
address_street
required Valid US street address. We may reject invalid addresses. Apartment/suite units, company names, etc. should be placed in address_unit
address_unit
optional
address_city
optional
address_state
optional
address_zip
required Five-digit US ZIP code as a string. Must be an accepted ZIP code.
address_info
optional Additional information to help with deliveries, e.g., broken buzzers, door codes.
package_no
optional Number of packages as a positive integer. Defaults to 1 if not specified.
package_weights
optional In pounds. String with numbers separated by commas (for example, "1.25,3,4.5"). The number of package weights must match package_no.
delivery_group
required day for daytime deliveries, night for nighttime deliveries, overnight for overnight deliveries between midnight and morning, and tbd for deliveries that are not yet scheduled.
delivery_date
required ISO format date If we receive the package before the selected date, we will hold onto it and only notify the customer on the selected date. If we receive the package after the selected date, both date and time window will be ignored, and the customer will be texted to schedule the delivery for that night.
delivery_start_time
delivery_end_time
optional, requires approval Only for use when delivery_group is night. Must be a valid time window.
external_id
optional String for storing an ID or something for your own reference.

Retrieving an order

You can retrieve the details of an order with just the order ID.

GET /orders/{ORDER_ID}
{
    "address_city": "NY",
    "address_info": "buzzer broken. text on arrival",
    "address_lat": 40.733543,
    "address_lng": -73.996323,
    "address_state": "NY",
    "address_street": "10 W 10th St",
    "address_unit": null,
    "address_zip": "10011",
    "completed_at": null,
    "created_at": "2014-12-31T19:33:28-05:00",
    "delivery_date": "2015-01-01",
    "delivery_end_time": null,
    "delivery_start_time": null,
    "email": null,
    "first_name": "John",
    "id": 9818556,
    "label_code": null,
    "label_url": null,
    "last_name": "Smith",
    "package_no": 1,
    "phone": "5551234567",
    "received_packages_at": null,
    "shipping_address": {
        "city": "Brooklyn",
        "state": "NY",
        "street": "48 Grattan St",
        "unit": "#9818556",
        "zip": "11237"
    },
    "sort_code": null,
    "status": "date_chosen",
    "test": false,
    "tracking_url": "https://www.fromparcel.com/tracking/9818556/"
}
Attributes
id
number
test
boolean
created_at
ISO format datetime string
notified_at
ISO format datetime string
received_packages_at
ISO format datetime string
completed_at
ISO format datetime string
customer
object A customer object
first_name
string
last_name
string
email
string
phone
string
address_street
string
address_unit
string
address_city
string
address_state
string
address_zip
string
address_lat
number
address_lng
number
address_info
string
label_code
string
label_url
string
shipping_address

object

address_street
string
address_unit
string
address_city
string
address_state
string
address_zip
string
sort_code
string
status
string can be date_chosen, scheduled, notified, en_route, delivered, or failed
tracking_url
string

Updating an order

Orders can only be updated before the predetermined cut-off time.

PATCH /orders/{ORDER_ID}
Request data:

{
  "delivery_date": "2015-01-02"
}

Response:
{
    "address_city": "NY",
    "address_info": "buzzer broken. text on arrival",
    "address_lat": 40.733543,
    "address_lng": -73.996323,
    "address_state": "NY",
    "address_street": "10 W 10th St",
    "address_unit": null,
    "address_zip": "10011",
    "completed_at": null,
    "created_at": "2014-12-31T19:33:28-05:00",
    "delivery_date": "2015-01-02",
    "delivery_end_time": null,
    "delivery_start_time": null,
    "email": null,
    "first_name": "John",
    "id": 9818556,
    "label_code": null,
    "label_url": null,
    "last_name": "Smith",
    "package_no": 1,
    "phone": "5551234567",
    "received_packages_at": null,
    "shipping_address": {
        "city": "Brooklyn",
        "state": "NY",
        "street": "48 Grattan St",
        "unit": "#9818556",
        "zip": "11237"
    },
    "sort_code": null,
    "status": "date_chosen",
    "test": false,
    "tracking_url": "https://www.fromparcel.com/tracking/9818556/"
}
Arguments

Same as POST arguments, except no arguments are required.

Delete an order

You may not delete an order after the cutoff time in your partner contract. If you try to delete an order that is not deletable, you will receive a 402 error.

DELETE /orders/{ORDER_ID}
{
  "deleted": true,
  "id": 9818556,
  "test": true
}
Attributes
id
number
test
boolean
deleted
boolean