NAV Navbar
http

API Overview

Here you can find the basics of interacting with the Roadie API.

Through the Roadie API your application can retrieve and manage shipments. Our API is organized around REST, and designed to use resource oriented URLs and HTTP response codes to indicate API errors.

Versioning

To avoid issues with backward incompatibility, we will version the API when there are any breaking changes. The current version of the API is v1, and the value is passed as part of the URL of the request.

Authentication

Authentication is handled via an access token included in the Authorization header of each request. Please contact Roadie support to retrieve your access token.

Authorization: Bearer <YOUR_ACCESS_TOKEN>

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Rate Limiting

Sample Throttled Response:

Status: 429
Content-Type: 'application/json'
Retry-After: 60

If too many requests are received using the same access token, that access token will be throttled. Throttled requests will receive a response with a status code of 429 and will contain a Retry-After header that indicates how many seconds the user should wait before making additional requests. Roadie currently limits each user to 10 requests per second, but that limit is subject to change. Please design your client to adhere to the Retry-After header, and not the current rate limit.

Estimates

Create an Estimate

Parameters

Sample Request:

POST /v1/estimates HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
  "items" : [
    {
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "quantity" : 1,
      "value" : 20
    }
  ],
  "pickup_location" : {
    "address" : {
      "street1" : "123 Main Street",
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305"
    }
  },
  "delivery_location" : {
    "address" : {
      "street1" : "456 Central Ave.",
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308"
    }
  },
  "pickup_after" : "2019-01-01T13:00:00Z",
  "deliver_between" : {
    "start" : "2019-01-01T21:00:00Z",
    "end" : "2019-01-01T23:00:00Z"
  }
}

Sample Response:

{
  "price" : 12.00,
  "size" : "large",
  "estimated_distance": 12.54
}
Name Type Description
items
(required)
array An array of one or more Item.
pickup_location
(required)
Location A Location object.
delivery_location
(required)
Location A Location object.
pickup_after
(required)
timestamp The time when the shipment is ready for pickup.
deliver_between
(required)
TimeWindow The window within which the shipment must be completed.

Shipments

The Shipments API will be your primary tool with Roadie. With this API you will be able to:

Sample Shipment object:

{
  "id" : 45245234,
  "reference_id" : "ABCDEFG12345",
  "description" : "General shipment description.",
  "state" : "assigned",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "contact" : {
      "name" : "Destination Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00.000Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00.000Z",
    "end" : "2017-12-26T20:00:00.000Z"
  },
  "options" : {
    "signature_required" : true,
    "notifications_enabled" : false,
    "over_21_required" : false,
    "over_18_required" : false,
    "extra_compensation" : 5.0,
    "trailer_required" : false
  },
  "tracking_number" : "RETHNKW354W3H438",
  "driver" : {
    "name" : "Jeff B.",
    "phone" : "7709999999"
  },
  "price" : 12.00,
  "estimated_distance": 3.456,
  "events": [
    {
      "name": "at_delivery",
      "occurred_at": "2017-12-25T10:38:43.467Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    },
    {
      "name": "delivery_confirmed",
      "occurred_at": "2017-12-25T12:23:54.325Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    }
  ],
  "created_at" : "2017-12-25T06:00:00.000Z",
  "updated_at" : "2017-12-25T06:00:00.000Z"
}
Name Type Description
id integer The unique ID of the shipment.
reference_id string The user supplied ID for the shipment.
alternate_id_1 string The user-supplied alternate identifier 1
alternate_id_2 string The user-supplied alternate identifier 2
description text A general description for the shipment, often containing important information for the driver. This field is globally visible to all users on the platform.
state string The current state of the shipment. See ShipmentState for all possible values.
items array An array of one or more Item.
pickup_location Location The address and contact info where the driver will pick up the shipment.
delivery_location Location The address and contact info where the driver will deliver the shipment.
pickup_after timestamp The time, in RFC 3339 format, after which the shipment is ready for pickup.
deliver_between TimeWindow The window within which the shipment must be completed.
options DeliveryOptions Any delivery options for the shipment.
tracking_number string A unique number used to track the shipment.
driver Driver The information about the assigned driver.
events array An array of one or more shipment Event
created_at timestamp The time when the shipment was created in RFC 3339 format.
updated_at timestamp The time when the shipment was last updated in RFC 3339 format.

Create a Shipment

Parameters

Sample Request:

POST /v1/shipments HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
  "reference_id" : "ABCDEFG12345",
  "idempotency_key" : "d6f9d5bb-1ba1-48d9-9125-6a61490a5ca5",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "description" : "General shipment description.",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "contact" : {
        "name" : "Destination Contact",
        "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00Z",
    "end" : "2017-12-26T20:00:00Z"
  },
  "options" : {
      "signature_required" : true,
      "notifications_enabled" : false,
      "over_21_required" : false,
      "over_18_required" : false,
      "extra_compensation" : 5.0,
      "trailer_required" : false,
      "decline_insurance" : true
  }
}

Sample Response:

{
  "id" : 152040,
  "reference_id" : "ABCDEFG12345",
  "description" : "General shipment description.",
  "state" : "scheduled",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "contact" : {
      "name" : "Destination Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00.000Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00.000Z",
    "end" : "2017-12-26T20:00:00.000Z"
  },
  "options" : {
    "signature_required" : true,
    "notifications_enabled" : false,
    "over_21_required" : false,
    "over_18_required" : false,
    "extra_compensation" : 5.0,
    "trailer_required" : false,
    "decline_insurance" : true
  },
  "tracking_number" : "RETHNKW354W3H438",
  "price" : 12.00,
  "estimated_distance": 3.456,
  "events": [
    {
      "name": "at_delivery",
      "occurred_at": "2017-12-25T10:38:43.467Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    },
    {
      "name": "delivery_confirmed",
      "occurred_at": "2017-12-25T12:23:54.325Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    }
  ],
  "created_at" : "2017-12-25T06:00:00.000Z",
  "updated_at" : "2017-12-25T06:00:00.000Z"
}
Name Type Description
reference_id (required) string The user supplied ID for the shipment. Max length 100 characters.
idempotency_key string A unique value generated by the user which the Roadie system will use to recognize subsequent retries of the same request. Duplicate requests with the same idempotency_key value will yield a 409 conflict response after the first successful 200 response. Can only be supplied when creating a shipment.
alternate_id_1 string The user-supplied alternate identifier 1
alternate_id_2 string The user-supplied alternate identifier 2
description text A general description for the shipment, often containing important information for the driver. This field is globally visible to all users on the platform. Max length 600 characters.
items
(required)
array An array of one or more Item.
pickup_location
(required)
Location A complete Location object.
delivery_location
(required)
Location A complete Location object.
pickup_after
(required)
timestamp The time when the shipment is ready for pickup.
pickup_between TimeWindow The window within which the shipment must be picked up. This value can take the place of pickup_after if you have specific pickup requirements.
deliver_between
(required)
TimeWindow The window within which the shipment must be completed.
options
(required)
DeliveryOptions Any delivery options for the shipment.
pickup_accessibility_features string A general description of any accessibility features the pickup location has.
delivery_accessibility_features string A general description of any accessibility features the delivery location has.
packaging_information string A general description of how the items are packaged to help prevent leakage or breakage.
events array An array of one or more shipment Event

Best Practices

Retrieve a Shipment

Sample Request:

GET /v1/shipments/152040 HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

Sample Response:

{
  "id" : 152040,
  "reference_id" : "ABCDEFG12345",
  "description" : "General shipment description.",
  "state" : "delivered",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "contact" : {
      "name" : "Destination Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00.000Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00.000Z",
    "end" : "2017-12-26T20:00:00.000Z"
  },
  "options" : {
    "signature_required" : true,
    "notifications_enabled" : true,
    "over_21_required" : true,
    "over_18_required" : true,
    "extra_compensation" : 5.0,
    "trailer_required": false
  },
  "tracking_number" : "RETHNKW354W3H438",
  "signatory_name" : "Jane Doe",
  "price" : 12.00,
  "estimated_distance": 3.456,
  "events": [
    {
      "name": "at_delivery",
      "occurred_at": "2017-12-25T10:38:43.467Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    },
    {
      "name": "delivery_confirmed",
      "occurred_at": "2017-12-25T12:23:54.325Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    }
  ],
  "created_at" : "2017-12-25T06:00:00.000Z",
  "updated_at" : "2017-12-25T06:00:00.000Z"
}

Retrieve a List of Shipments

Sample Request:

GET /v1/shipments?reference_ids=ABC123,ABC456 HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

Sample Response

[
  {
    "id" : 45245234,
    "reference_id" : "ABC123",
    "description" : "General shipment description.",
    "state" : "assigned",
    "alternate_id_1": "111",
    "alternate_id_2": "222",
    "items" : [
      {
        "description" : "Item description",
        "reference_id" : null,
        "length" : 1.0,
        "width" : 1.0,
        "height" : 1.0,
        "weight" : 1.0,
        "value" : 20.00,
        "quantity" : 1
      }
    ],
    "pickup_location" : {
      "address" : {
        "name" : "Origin Location",
        "store_number" : "12324",
        "street1" : "123 Main Street",
        "street2" : null,
        "city" : "Atlanta",
        "state" : "GA",
        "zip" : "30305",
        "latitude": 33.74903,
        "longitude": -85.38803
      },
      "contact" : {
        "name" : "Origin Contact",
        "phone" : "4049999999"
      },
      "notes" : null
    },
    "delivery_location" : {
      "address" : {
        "name" : "Destination Location",
        "store_number" : null,
        "street1" : "456 Central Ave.",
        "street2" : null,
        "city" : "Atlanta",
        "state" : "GA",
        "zip" : "30308",
        "latitude": 33.04131,
        "longitude": -84.18303
      },
      "contact" : {
        "name" : "Destination Contact",
        "phone" : "4049999999"
      },
      "notes" : null
    },
    "pickup_after" : "2017-12-26T06:00:00.000Z",
    "deliver_between" : {
      "start" : "2017-12-26T06:00:00.000Z",
      "end" : "2017-12-26T20:00:00.000Z"
    },
    "options" : {
      "signature_required" : true,
      "notifications_enabled" : false,
      "over_21_required" : false,
      "over_18_required" : false
    },
    "tracking_number" : "RETHNKW354W3H438",
    "driver" : {
      "name" : "Jeff B.",
      "phone" : "7709999999"
    },
    "price" : 12.00,
    "estimated_distance": 3.456,
    "events": [
      {
        "name": "at_delivery",
        "occurred_at": "2017-12-25T10:38:43.467Z",
        "location": {
          "latitude": 36.123456,
          "longitude": -82.345678
        }
      },
      {
        "name": "delivery_confirmed",
        "occurred_at": "2017-12-25T12:23:54.325Z",
        "location": {
          "latitude": 36.123456,
          "longitude": -82.345678
        }
      }
    ],
    "created_at" : "2017-12-25T06:00:00.000Z",
    "updated_at" : "2017-12-25T06:00:00.000Z"
  },
  {
    "id" : 152040,
    "reference_id" : "ABC456",
    "description" : "General shipment description.",
    "state" : "delivered",
    "alternate_id_1": 333,
    "alternate_id_2": 444,
    "items" : [
      {
        "description" : "Item description",
        "reference_id" : null,
        "length" : 1.0,
        "width" : 1.0,
        "height" : 1.0,
        "weight" : 1.0,
        "value" : 20.00,
        "quantity" : 1
      }
    ],
    "pickup_location" : {
      "address" : {
        "name" : "Origin Location",
        "store_number" : "12324",
        "street1" : "123 Main Street",
        "street2" : null,
        "city" : "Atlanta",
        "state" : "GA",
        "zip" : "30305",
        "latitude": 33.74903,
        "longitude": -85.38803
      },
      "contact" : {
        "name" : "Origin Contact",
        "phone" : "4049999999"
      },
      "notes" : null
    },
    "delivery_location" : {
      "address" : {
        "name" : "Destination Location",
        "store_number" : null,
        "street1" : "456 Central Ave.",
        "street2" : null,
        "city" : "Atlanta",
        "state" : "GA",
        "zip" : "30308",
        "latitude": 33.04131,
        "longitude": -84.18303
      },
      "contact" : {
        "name" : "Destination Contact",
        "phone" : "4049999999"
      },
      "notes" : null
    },
    "pickup_after" : "2017-12-26T06:00:00.000Z",
    "deliver_between" : {
      "start" : "2017-12-26T06:00:00.000Z",
      "end" : "2017-12-26T20:00:00.000Z"
    },
    "options" : {
      "signature_required" : true,
      "notifications_enabled" : true,
      "over_21_required" : true,
      "over_18_required" : true,
    },
    "tracking_number" : "RETHNKW354W3H438",
    "signatory_name" : "Jane Doe",
    "price" : 12.00,
    "estimated_distance": 3.456,
    "events": [
      {
        "name": "at_delivery",
        "occurred_at": "2017-12-25T10:38:43.467Z",
        "location": {
          "latitude": 36.123456,
          "longitude": -82.345678
        }
      },
      {
        "name": "delivery_confirmed",
        "occurred_at": "2017-12-25T12:23:54.325Z",
        "location": {
          "latitude": 36.123456,
          "longitude": -82.345678
        }
      }
    ],
    "created_at" : "2017-12-25T06:00:00.000Z",
    "updated_at" : "2017-12-25T06:00:00.000Z"
  }
]

Query Parameters

Name Example Description
ids ids=1,2,3,4 A list of comma-separated id values, supplied as a query parameter. The id refers to the unique Roadie shipment "id" returned when a shipment is successfully created.
reference_ids reference_ids=ABC,DEF A list of comma-separated reference id values, supplied as a query parameter. The reference id refers to the "reference_id" supplied by the user when a new shipment is created. Note: Because reference_id values are not unique, passing in a single value can result in multiple records returned.

Update a Shipment

Parameters

Sample Request:

PATCH /v1/shipments/152040 HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
  "reference_id" : "ABCDEFG12345",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "description" : "General shipment description.",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305"
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308"
    },
    "contact" : {
      "name" : "Destination Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00Z",
    "end" : "2017-12-26T20:00:00Z"
  },
  "options" : {
    "signature_required" : true,
    "notifications_enabled" : true,
    "over_21_required" : true,
    "over_18_required" : true,
    "extra_compensation" : 5.0,
    "trailer_required": false
  }
}

Sample Response:

{
  "id" : 152040,
  "reference_id" : "ABCDEFG12345",
  "description" : "General shipment description.",
  "state" : "scheduled",
  "alternate_id_1": "111",
  "alternate_id_2": "222",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
  "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "contact" : {
      "name" : "Origin Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "contact" : {
      "name" : "Destination Contact",
      "phone" : "4049999999"
    },
    "notes" : null
  },
  "pickup_after" : "2017-12-26T06:00:00.000Z",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00.000Z",
    "end" : "2017-12-26T20:00:00.000Z"
  },
  "options" : {
    "signature_required" : true,
    "notifications_enabled" : true,
    "over_21_required" : true,
    "over_18_required" : true,
    "extra_compensation" : 5.0,
    "trailer_required": false
  },
  "tracking_number" : "RETHNKW354W3H438",
  "price" : 12.00,
  "estimated_distance": 3.456,
  "events": [
    {
      "name": "at_delivery",
      "occurred_at": "2017-12-25T10:38:43.467Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    },
    {
      "name": "delivery_confirmed",
      "occurred_at": "2017-12-25T12:23:54.325Z",
      "location": {
        "latitude": 36.123456,
        "longitude": -82.345678
      }
    }
  ],
  "created_at" : "2017-12-25T06:00:00.000Z",
  "updated_at" : "2017-12-25T06:00:00.000Z"
}
Name Type Description
reference_id string The user supplied ID for the shipment.
alternate_id_1 string The user-supplied alternate identifier 1
alternate_id_2 string The user-supplied alternate identifier 2
description text A general description for the shipment, often containing important information for the driver. This field is globally visible to all users on the platform.
items array An array of one or more Item.
pickup_location Location A complete Location object.
delivery_location Location A complete Location object.
pickup_after timestamp The time when the shipment is ready for pickup.
deliver_between TimeWindow The window within which the shipment must be completed.
options DeliveryOptions Any delivery options for the shipment.
pickup_accessibility_features string A general description of any accessibility features the pickup location has.
delivery_accessibility_features string A general description of any accessibility features the delivery location has.
packaging_information string A general description of how the items are packaged to help prevent leakage or breakage.
events array An array of one or more shipment Event

Cancel a Shipment

Sample Request:

DELETE /v1/shipments/152040 HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
    "cancellation_code": "item_not_ready",
    "cancellation_comment": "item was not ready for pickup"
}
Name Type Description
cancellation_code string A cancellation code matching the reason for the cancellation.
cancellation_comment string An additional comment explaining the cancellation reason.

A shipment can be canceled anytime before the driver has confirmed pickup. Cancellations posted after the assigned driver is en route to the pickup location will incur a cancellation fee to account for the driver's time spent on the order.

A list of valid cancellation codes can be found here. Not all codes may not be relevant for senders.

Leave a Tip for the Driver

Sample Request:

POST /v1/shipments/152040/tips HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
  "amount": 5.0
}

Sample Response:

{
  "amount": 5.0
}
Name Type Description
amount float The amount to tip driver in USD.

This endpoint may only be called once. Subsequent calls will return 1003 error as a tip has already been set.

Leave a Rating for the Driver

Sample Request:

POST /v1/shipments/152040/ratings HTTP/1.1
Content-Type: application/json
Authorization: Bearer ...

{
  "value": 5
}

Sample Response:

{
  "value": 5
}
Name Type Description
value integer The rating for the driver.

Rating values must be in the range 1 to 5 (inclusive), with a value of 1 indicating poor performance and a value of 5 indicating excellent performance.

This endpoint may only be called once. Subsequent calls will return 1003 error as a rating has already been set.

Retrieve a Signature Image

Sample Request:

GET /v1/shipments/152040/images/signature HTTP/1.1
Authorization: Bearer ...

If a signature is collected, returns raw image data.

Retrieve a Pickup Image

Sample Request:

GET /v1/shipments/152040/images/pickup HTTP/1.1
Authorization: Bearer ...

Returns raw image data.

Retrieve a Delivery Image

Sample Request:

GET /v1/shipments/152040/images/delivery HTTP/1.1
Authorization: Bearer ...

Returns raw image data.

Retrieve a Barcode Label

Sample Request:

GET /v1/shipments/152040/label?format=PNG HTTP/1.1
Authorization: Bearer ...

If barcode scanning is enabled for your account, you can request a barcode label from Roadie to include with your order. The label will be returned as a PNG or PDF base-64 encoded string as noted by the format type. If no format type is passed, a PNG label will be returned.

Name Type Description
Format (optional) PNG or PDF Define this value if you want to specify a PNG or PDF label.

Barcode Scanning

If your organization would like to verify the parcel(s) in your delivery using barcodes, Roadie can enable a barcode requirement for your shipment requests. If enabled, Roadie will require a barcode scan at pickup and dropoff to ensure that the shipment reached its destination.

Roadie supports barcode scanning both at the order level (i.e. one scan per order), and at the item level (i.e. multiple scans per order). Currently, item-level scanning is only supported with our API integration.

Typically the barcode will match the order number which is sent to Roadie as a reference_id in your request. Contact your account manager if you want to utilize a different value for your barcode, such as a tracking number.

Roadie also provides a manual barcode entry fallback for instances where the code is torn or the scanner isn’t working. Please include a human readable printout of the barcode as well so that the driver can manually enter the barcode in these instances.

Single Barcode Scan - Option 1

Pass the barcode value as the shipment-level reference_id.

Sample Request (abridged)

{
  "reference_id" : "ROADIE-zx24lz7mQsYRagyq",
  "idempotency_key" : "b3ecea95-3120-47ac-9334-1b7a014c1359",
  "alternate_id_1": "5271f0f5-6b06-4165-9128-cc1a546911d7",
  "description" : "General shipment description.",
  "items" : [
    {
      "description" : "Item description",
      "length" : 10.0,
      "width" : 12.0,
      "height" : 8.0,
      "weight" : 15.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],

  ...

  "options" : {
      "signature_required" : false
  }
}

This option is best suited to senders who will use the primary order number as the value for the barcode.

Single Barcode Scan - Option 2

Pass the barcode value as an item-level reference_id.

Sample Request (abridged)

{
  "reference_id" : "ROADIE-zx24lz7mQsYRagyq",
  "idempotency_key" : "b3ecea95-3120-47ac-9334-1b7a014c1359",
  "alternate_id_1": "5271f0f5-6b06-4165-9128-cc1a546911d7",
  "description" : "General shipment description.",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : "ROADIE-Cc5WaTZHgQlcZ5Ss",
      "length" : 10.0,
      "width" : 12.0,
      "height" : 8.0,
      "weight" : 15.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],

  ...

  "options" : {
      "signature_required" : false
  }
}

We recommend this option if the barcode string is different from the primary order number, or if you ever expect to have more than one barcode scan per order.

Multi-Barcode Scan

Create a shipment with multiple barcode scans.

Orders that will require drivers to scan more than one barcode must pass each barcode as the reference_id for a unique item in the request.

Sample Request (abridged)

{
  "reference_id" : "ROADIE-zx24lz7mQsYRagyq",
  "idempotency_key" : "b3ecea95-3120-47ac-9334-1b7a014c1359",
  "alternate_id_1": "5271f0f5-6b06-4165-9128-cc1a546911d7",
  "description" : "General shipment description.",
  "items" : [
    {
      "description" : "Item description",
      "reference_id" : "ROADIE-zx24lz7mQsYRagyq-001",
      "length" : 10.0,
      "width" : 12.0,
      "height" : 8.0,
      "weight" : 15.0,
      "value" : 20.00,
      "quantity" : 1
    },
    {
      "description" : "Item description",
      "reference_id" : "ROADIE-zx24lz7mQsYRagyq-002",
      "length" : 10.0,
      "width" : 12.0,
      "height" : 8.0,
      "weight" : 15.0,
      "value" : 20.00,
      "quantity" : 1
    },
    {
      "description" : "Item description",
      "reference_id" : "ROADIE-zx24lz7mQsYRagyq-003",
      "length" : 10.0,
      "width" : 12.0,
      "height" : 8.0,
      "weight" : 15.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],

  ...

  "options" : {
      "signature_required" : false
  }
}

Valid Types

Roadie’s barcode scanner is compatible with the following types of labels.

Format Types
Linear Code 39, Code 93, Code 128, EAN-8, EAN-13, ITF, UPC-E
2D Codes Aztec, Data Matrix, PDF417, QR Code

Data Types

Item

Represents the attributes of an Item.

Fields

Name Type Description
description
(required)
string The description of the item. Max length 200 characters.
reference_id string The user supplied ID for the item. Max length 100 characters.
value
(required)
float The monetary value of the item. If the item quantity is greater than 1, the value should represent the monetary value of a single item.
length
(required)
float The length in inches of the item.
width
(required)
float The width in inches of the item.
height
(required)
float The height in inches of the item.
weight
(required)
float The weight in pounds of the item.
quantity
(required)
integer The number of items included in the shipment.

Location

Represents a pickup or delivery location. Note: A contact is required for shipment requests.

Fields

Name Type Description
address
(required)
Address The address information.
contact
(required for Shipment)
Contact The contact information.
notes string Any additional information the drivers needs regarding the location. Max length 500 characters.

Address

Represents an address.

Fields

Name Type Description
name string The name of the location if applicable. This helpful for the driver if the location is a business. Max length 200 characters.
store_number string If the address is a retail location, this is the store identifier. Max length 20 characters.
street1
(required)
string The first line of the address. Max length 200 characters.
street2 string The second line of the address. Max length 200 characters.
city
(required)
string The city. Max length 200 characters.
state
(required)
string The two letter state code.
zip
(required)
string The postal code. Max length 10 characters.
latitude float exact pickup/delivery latitude.
longitude float exact pickup/delivery longitude.

Best Practices

Contact

Represents a pickup or delivery contact.

Fields

Name Type Description
name
(required)
string The name of the contact. Max length 200 characters.
phone
(required)
string The phone number of the contact. Max length 10 characters.

DeliveryOptions

Represents delivery options.

Fields

Name Type Description
signature_required
(required)
boolean Indicates whether or not driver must receive a signature from the recipient.
notifications_enabled boolean Indicates whether or not the recipient should receive SMS updates for their delivery.
over_21_required boolean Indicates if the driver must be over 21 to be eligible to deliver the item (typically for alcohol deliveries).
over_18_required boolean Indicates if the driver must be over 18 to be eligible to deliver the item (typically for medicationsß).
extra_compensation float Specify additional compensation for the driver prior to assignment.
trailer_required boolean Indicates if the driver must use a trailer to deliver the item(s).
decline_insurance boolean Indicates if Roadie Protection Plan is applied to items in your gig.

TimeWindow

Represents a span of time within which the shipment should be delivered.

Fields

Name Type Description
start
(required)
timestamp The start of the window in RFC 3339 format.
end
(required)
timestamp The end of the window in RFC 3339 format.

Driver

Represents information about the driver.

Fields

Name Type Description
name string The driver's name.
phone string The driver's phone number.

Enums

ShipmentState

Defines the state of a shipment

Fields

Name Description
scheduled The shipment has been scheduled, and awaiting driver assignment.
assigned A driver has been assigned, and the driver is headed to the pickup location.
en_route The items have been picked up, and are en route to the delivery location.
delivered The items have been successfully delivered.
attempted The shipment was attempted, but unsuccessful.
returned The shipment was unsuccessful, and the items were returned to the pickup location.
canceled The shipment was canceled.
expired The delivery window passed before a driver could be assigned.

Routing

Here at Roadie, we like to assign drivers to routes that are on the way to where they are already going. We also try to simplify life for our shippers when they have multiple packages for pick-up headed to the same area. For instance, if there are three gigs leaving a certain sender location at the same time, if all of those gigs can easily fit into a sedan, and if an efficient route exists that serves all three deliveries, Roadie’s routing system will attempt to consolidate the orders. Doing so reduces the time and mileage required to get all three gigs delivered.

Best Practices

To take advantage of Routing with Roadie, keep these guidelines in mind:

Note that Roadie will only batch orders from the same sender and Roadie drivers will not have orders from multiple senders.

Round Trips

You may have a use case where you need multiple legs in one shipment route where the driver returns to the origin location after the delivery. To do so, follow the guidelines below:

Sample Round Trip (abridged):

{
  "reference_id" : "ABCDEFG12345",
  "idempotency_key" : "b3ecea95-3120-47ac-9334-1b7a014c1359",
  "description" : "round trip",
  "items" : [
    {
      "description" : "Item description",
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],

 ... 

    "delivery_batch" : {
      "reference_id": "aaaa-bbbb-cccc",
      "sequence_number": 1
    },
}

Webhooks

If a webhook has been configured for your account, Roadie will automatically post JSON to the provided URL for a number of events that occur during the delivery process.

Shipment Events

Sample webhook payloads:

{
  "event" : "shipment.driver_assigned",
  "data" : {
    "id" : 5678,
    "driver_id" : "b0ffb6a9-0bdd-45a2-a502-126e3f4627ed",
    "occurred_at" : "2018-01-14T19:20:00Z",
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "driver" : {
      "name" : "Beth Johnson",
      "phone" : "5555555555",
      "vehicle" : {
        "category" : "sedan",
        "color" : "blue",
        "make" : "Full-Sized",
        "model" : "Car"
      }
    },
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.en_route_to_pickup",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.at_pickup",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event": "shipment.pickup_confirmed",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "attachment" : {
      "file_name" : "image.jpg",
      "mime_type" : "image/jpeg",
      "url": "https://connect.roadie.com/v1/shipments/5678/images/pickup"
    },
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.en_route_to_delivery",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.at_delivery",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.delivery_confirmed",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "attachment" : {
      "file_name" : "image.jpg",
      "mime_type" : "image/jpeg",
      "url": "https://connect.roadie.com/v1/shipments/5678/images/signature"
    },
    "signatory_name" : "Jane Doe",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event": "shipment.delivery_details_added",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "attachment" : {
      "file_name" : "image.jpg",
      "mime_type" : "image/jpeg",
      "url": "https://connect.roadie.com/v1/shipments/5678/images/delivery"
    }
  }
}

{
  "event" : "shipment.delivery_attempted",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "return_code" : "recipient_refused_damaged",
    "return_notes" : "Additional details about the damaged item.",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.returned",
  "data" : {
    "id" : 5678,
    "reference_id" : "RF1234567",
    "return_id" : 5679,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.canceled",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "reference_id" : "RF1234567",
    "cancellation_code" : "item_not_as_described",
    "cancellation_notes" : "Item was too large to fit in the assigned driver's vehicle.",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event": "shipment.driver_approaching_pickup",
  "data": {
    "id": 3754002,
    "occurred_at": "2020-10-16T19:37:46Z",
    "latitude": 35.3078628,
    "longitude": -82.4602295,
    "reference_id": "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event": "shipment.driver_approaching_delivery",
  "data": {
    "id": 3754002,
    "occurred_at": "2020-10-16T19:37:46Z",
    "latitude": 35.3078628,
    "longitude": -82.4602295,
    "reference_id": "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event": "shipment.tracking_updated",
  "data": {
    "id": 3754002,
    "occurred_at": "2020-10-16T19:37:46Z",
    "latitude": 35.3078628,
    "longitude": -82.4602295,
    "reference_id": "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.driver_unassigned",
  "data" : {
    "id" : 5678,
    "driver_id" : "b0ffb6a9-0bdd-45a2-a502-126e3f4627ed",
    "occurred_at" : "2018-01-14T19:20:00Z",
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "driver" : {
      "name" : "Beth Johnson",
      "phone" : "5555555555"
    },
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}

{
  "event" : "shipment.created",
  "data" : {
    "id" : 5678,
    "reference_id" : "RF1234567",
    "state" : "scheduled",
    "alternate_id_1" : "111",
    "alternate_id_2" : "222",
    "tracking_number": "8e78c2b703309618",
    "estimated_distance" : 3.5,
    "created_at" : "2017-12-25T06:00:00.000Z",
    "items" : [
    {
      "description" : "Item description",
      "reference_id" : null,
      "length" : 1.0,
      "width" : 1.0,
      "height" : 1.0,
      "weight" : 1.0,
      "value" : 20.00,
      "quantity" : 1
    }
  ],
    "pickup_location" : {
    "address" : {
      "name" : "Origin Location",
      "store_number" : "12324",
      "street1" : "123 Main Street",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30305",
      "latitude": 33.74903,
      "longitude": -85.38803
    },
    "delivery_location" : {
    "address" : {
      "name" : "Destination Location",
      "store_number" : null,
      "street1" : "456 Central Ave.",
      "street2" : null,
      "city" : "Atlanta",
      "state" : "GA",
      "zip" : "30308",
      "latitude": 33.04131,
      "longitude": -84.18303
    },
    "pickup_after" : "2017-12-26T06:00:00Z",
    "deliver_between" : {
      "start" : "2017-12-26T06:00:00Z",
      "end" : "2017-12-26T20:00:00Z"
        }
      }
    }
  }
}

{
  "event": "grouping.pickup_grouping_identified",
  "data": {
    "id": "5632c440-df4f-4c8c-91e6-ac59997c9f91",
    "friendly_id": "zyxwvu",
    "occurred_at": "2018-01-14T19:03:04+00:00",
    "shipments": [
      {
        "id": 3754002,
        "reference_id": "RF1234567",
        "tracking_number": "RETHNKW354W3H438",
        "_ref": "https://connect.roadie.com/v1/shipments/3754002"
      }
    ]
  }
}

{
  "event": "shipment.delivery_confirmed_with_details",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20:00Z",
    "latitude" : 33.640065,
    "longitude" : -84.411257,
    "reference_id" : "RF1234567",
    "tracking_number": "8e78c2b703309618",
    "left_at_location": { // Key may be absent in rare situations
      "name": "handed_to_recipient",
      "description": "Items were handed directly to the recipient."
    },
    "attachment" : [
      {
        "image_type" : "signature",
        "mime_type" : "image/jpeg",
        "url": "https://connect.roadie.com/v1/shipments/5678/images/signature/file_name.jpeg"
      },
      {
        "image_type" : "proof_of_delivery",
        "mime_type" : "image/jpeg",
        "url": "https://connect.roadie.com/v1/shipments/5678/images/delivery/file_name.jpeg"
      }
    ],
    "signatory_name": "Marc Gorlin"
  }
}

{
  "event": "shipment.reposted",
  "data": {
    "id": 5679,
    "reference_id": "RF1234567",
    "parent_id": 5678,
    "occurred_at": "2018-01-14T19:20:00Z",
    "tracking_number": "8e78c2b703309618",
    "parent_tracking_number": "0c6227875c35e957",
    "delivery_batch": {
      "sequence_number": 1,
      "reference_id": "8b352e51-edc6-47f2-bb9a-51d14689308c"
    }
  }
}
Name Description
driver_assigned A driver has been assigned to the shipment.
en_route_to_pickup The driver is headed to the pickup location.
at_pickup The driver is at the pickup location.
pickup_confirmed The driver has successfully picked up the shipment.
en_route_to_delivery The driver is headed to the delivery location.
at_delivery The driver is at the delivery location.
delivery_confirmed The driver has successfully delivered the shipment. If a signature was collected, an attachment property will be returned.
delivery_details_added The driver has submitted a delivery photo.
delivery_attempted The driver was unsuccessful in delivering the shipment.
returned The shipment was undeliverable and is being returned to the origin location.
canceled The shipment has been canceled.
driver_approaching_pickup The driver is near the pickup location.
driver_approaching_delivery The driver is near the delivery location.

Additional Webhooks

The following webhooks may be enabled upon request.

Name Description
tracking_updated A new tracking point has been received.
driver_unassigned The driver has removed themselves or has been removed from a gig.
created The gig has successfully been created
grouping.pickup_grouping_identified Sent before pickup. A group of consolidated shipments to be picked up by a single driver.
delivery_confirmed_with_details Consolidates both the delivery_confirmed and the delivery_details_added into a single event.
reposted A new shipment has been reposted by Roadie after the initial shipment expired

Best Practices

Authentication Methods

Roadie supports the following methods of authentication with webhooks.

Method Description
basic An Authorization header is set with a base64 encoded provided username and password
bearer token An Authorization header is set with a provided bearer token
x-api-key An x-api-key header is set with a provided token

Return Codes

When a driver is unable to deliver your shipment, the shipment.delivery_attempted webhook event will include a return code. Return notes may also optionally be included in the payload if more information about the failed delivery is necessary.

Return Code Description
recipient_refused_damaged Customer rejected item because of damage.
recipient_refused Customer refused delivery for some other reason.
dest_address_not_found The destination address is incorrect.
dest_address_inaccessible The delivery address is inaccessible for some reason.
signature_required Not able to get the required signature.
age_verfication_failure Recipient age either cannot be verified or is too young to receive the delivery.
delivery_time_early Attempted delivery prior to delivery start time.
delivery_time_expired Time limit exceeded for an order with a must deliver by timeframe.
cold_chain_compliance Delivery exceeded cold chain compliance requirements (for groceries).
recipient_incorrect The recipient was incorrect.
recipient_unavailable The recipient was unavailable to receive the item.
order_canceled_after_pickup The order was canceled after the pick up requiring a return.
other Did not fit one of the other categories. Notes will be included.

Cancellation Codes

When your shipment has been canceled, the shipment.canceled webhook event will include a cancellation code. Cancellation notes may also optionally be included in the payload if more information about the cancellation is necessary.

Cancellation Code Description
address_inaccessible The driver was unable to reach the pickup location.
address_incorrect The pickup address was incorrect.
cold_chain_violation Delivery exceeded cold chain compliance requirements (for groceries).
contact_not_available A contact was not available and was required for access to the location.
delivery_deadline_passed The delivery deadline for the the item has already passed.
driver_delayed The driver was delayed and unable to pickup the item.
driver_canceled The driver canceled the pickup of the item.
duplicate_order The order was a duplicate of an existing order.
item_already_delivered The item has already been delivered.
item_damaged The item was damaged at time of pickup.
item_not_as_described The description for the item was not accurate.
item_not_in_stock The item was not available.
item_not_ready The item was not ready at time of pickup.
order_canceled The order was canceled.
order_incomplete The order did not have all the items requested.
order_not_found The order was not found by the driver.
wait_time_exceeded The time for the driver to pickup the order was too long.
other Did not fit one of the other categories. Notes will be included.

Status Codes

Unless stated otherwise the following HTTP status codes will be generated for requests.

Status Meaning Required Action
200 Request successful N/A
201 Object creation successful N/A
400 Invalid or incomplete post data Review the returned errors and fix the defects.
401 Access token is missing of invalid Bad session token or not present
404 Endpoint does not exist Verify the endpoint URL against the Roadie documentation.
429 Too many requests See Rate Limiting.
500 Internal Server Error There was an internal problem with our server. Try again later.
503 Service Unavailable Roadie is temporarily offline for maintenance. Please try again later.

Errors

Sample error response:

{
  "errors" : [
    {
      "code" : 1001,
      "parameter" : "pickup_location",
      "message" : "Pickup location can't be blank."
    }
  ]
}

If a 400 status code is received for a create or update request, a collection of errors will be returned.

Error Code Meaning
1001 Required parameter is missing.
1002 Parameter is invalid.
1003 Parameter violates system rules.
1004 Supplied address cannot be found.
1005 Valid route cannot be made between supplied addresses.
1006 Shipment not found with supplied ID.

Launch Preparation

We suggest testing your Roadie integration in a sandbox environment before going live. You can contact Roadie API Support when you are ready to begin testing.

Sandbox Testing

You should test your API orders in our sandbox environment. You can trigger an auto delivery by following the steps below:

Commands

Command Field Example Description
return delivery_location→notes "Please return this shipment." Simulates a return scenario. Note: This command is case sensitive.
cancel pickup_location→notes "Please cancel this shipment." Simulates a cancellation scenario. Note: This command is case sensitive.
timing description "My gig description. --timing 60" Set the delivery event interval timing in seconds. Value must be between 15 and 900 seconds.

Certification

After you have completed your end-to-end tests, please create a few test orders and share those order ID numbers with Roadie. Roadie will review the data included in these requests to ensure that the data is valid and will not cause issues with live Roadie drivers.

Please use addresses and timestamps that would make sense for the region where you will be utilizing Roadie.

Please include orders in the following scenarios:

Upon certifying your data the Integrations Team at Roadie can provide you with production credentials unless otherwise specified by your business development representative or account manager.

Frequently Asked Questions

Can I batch deliveries together?
Our system automatically takes care of consolidating multiple orders together for a single driver to pick up, taking several factors like delivery windows and addresses into consideration, as long as you give us sufficient time before the pickup time (about 60 minutes). Review our Routing Best Practices for assistance.
Can I select my driver?
Roadie drivers select which shipments they want to accept.
How long should the delivery window be?
The length of the delivery window is usually determined by your contract's SLA if applicable.
How far does Roadie deliver?
Roadie can deliver up to 350 miles but you can work with your account manager to set a delivery radius for your store.
Can I update my order status?
You cannot manually update the status of your order (e.g. driver_assigned, at_pickup). You can update a shipment at any time before a driver has been assigned. You can cancel a shipment at any time before a driver has confirmed pickup.
What if I don't have access to an item's dimensions or weight at shipment creation?
Although it would be optimal to have the specific data as it's used for determining vehicle capacity necessary, if you don't have the information at shipment creation time, you can provide a rough estimate of the dimensions and weight.
How much time do I need to provide between the shipment request and pickup time?
Ideally, you should provide at least 60 minutes between your request and pickup time to allow Roadie to batch your orders which is more efficient for the Roadie driver and cheaper for you as well. A 60 minute window also allows your packers more time to prepare the order for delivery so that the Roadie driver is not waiting after the pickup time. If a 60 minute window is not provided, the order may not be eligible for batching and may be matched with a driver as soon as possible.
What if my orders contain sensitive information or age-restricted products such as alcohol?
In all of your orders, you will need to specify whether a signature is required using the signature_required field. This is a boolean value you can set to true if you need to ensure your item was delivered. Roadie also provides two fields for age-restricted deliveries: over_18_required and over_21_required. These fields will require that the driver must be of age to deliver a product. Roadie verifies that the driver is of age before allowing them to bid on those shipments.
How does Roadie calculate distance?
Roadie calculates distance based on miles driven by the driver.
Can I make API calls outside of the US?
We currently do not support non-US-originated IP addresses. If you’re outside of the United States please use a VPN when creating your shipments. Note, this rule also applies to our Sender Portal.
Can I receive an “ETA” included in a webhook event?
Yes, this is possible with specific webhooks events. Please reach out to api_support@roadie.com and we can assist with enabling this feature.
What happens if a driver doesn’t accept my Gig?
The order will expire after the deadline to deliver the order has passed, then we’ll send a canceled webhook event. This will allow you to decide what to do with that undelivered gig.

Roadie does have an option for automatic reposts for expired gigs. If this aligns with your business goals, please contact api_support@roadie.com for more information.
How do I know if the Roadie services are down?
Please visit our status page at status.roadie.com for information on outages and scheduled maintenance.