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.

The Authorization header must be sent for every request unless stated otherwise. Not doing so will result in a unauthorized response.

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:

Create and schedule shipments
Retrieve information on shipments
- Shipment logistics details
- Signature image (if enabled)
- Pickup image (if enabled)
- Delivery image (if enabled)
Update shipment details (before a driver is assigned)
Cancel a shipment (before a driver has picked up the shipment)
Leave a tip
Barcode scanning

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,
  "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

pickup_after must be a time set in the future. For immediate pickup, consider NOW() + 1 minute to avoid cases where the request may be take more than a second to complete.
pickup_after and deliver_between→start should be the same value

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:

PUT /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

Roadie will automatically geocode the address and return a latitude and longitude
If latitude and longitude are provided we will pass the exact coordinates to drivers. This is particularly useful if the location is a large building or complex.

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 recipient must be over 21 to be eligible to receive the item. The driver will scan the recipient's ID for verification. This will also ensure the driver is at least 21 years old.
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:

Advance notice - Providing at least 60 minutes between your shipment request and pickup time will provide Roadie’s algorithm more time to consolidate your deliveries. If you want a few orders to be batched it helps to send those requests around the same time.
Pickup time - If you intend to batch orders, please ensure that the orders have similar pickup times and that the Roadie driver won’t be waiting for items to be ready.
Deadlines - We take deadlines into consideration and if one order in a group of more orders has a tight deadline or items that can expire it may be excluded from a batched route
Efficiency - We take route efficiency into consideration and if two orders are ten miles in opposite directions we typically will not route them together
Vehicle Size - If items are particularly large they may not be good candidates for routing

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:

Send all shipment requests at around the same time, with >=60 minute lead time to help optimize routing
Send separate shipment requests for each leg of the journey
Include a note that this is a “round trip” in the shipment description
Include a delivery_batch parameter with a reference_id to tie together the batch as well as a sequence_number to indicate which stop of the route it is
- reference_id should be the same for all the legs of a single trip
- sequence_number should increment with each leg of the journey

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.

Please note that webhook payloads may be added to over time and as the technology updates

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"
      }, 
      "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "attachments" : {
      "file_name" : "image.jpg",
      "mime_type" : "image/jpeg",
      "url": "https://connect.roadie.com/v1/shipments/5678/images/pickup"
    },
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "attachments" : {
      "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "attachments" : {
      "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",
    "related_shipments": [
            46833232
        ],
      "parent_tracking_number": "21b2233a96b92cd"
    },
    "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

Drivers may be reassigned at anytime before pickup has been confirmed. In this case, it's possible that additional shipment.driver_assigned, shipment.en_route_to_pickup, and shipment.at_pickup webhooks may be sent during the same shipment.

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:

Create a shipment with an immediate delivery window. In practice, that looks like a shipment with a deliver_between→start that is less than 30 minutes in the future.
The automatic process should start to send events within ~30 seconds, and once events begin, you should receive events every 15 seconds or so, up until delivery is complete.
By default, the auto-process will complete delivery (happy path). If you'd like to simulate a return scenario, see the commands 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:

Happy path (single order)
Happy path (multiple orders)
Return path

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.