NAV
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 200 requests per minute, but that limit is subject to change. Please design your client to adhere to the Retry-After header, and not the current rate limit.

Shipments

Sample Shipment object:

{
  "id" : 45245234,
  "reference_id" : "ABCDEFG12345",
  "state" : "assigned",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
    "signature_required" : true
  },
  "tracking_number" : "RETHNKW354W3H438",
  "driver" : {
    "name" : "Jeff B.",
    "phone" : "7709999999"
  },
  "created_at" : "2017-12-25T06:00:00-06:00",
  "updated_at" : "2017-12-25T06:00:00-06:00"
}
Name Type Description
id integer The unique ID of the shipment.
reference_id string The user supplied ID for the shipment.
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.
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",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
      "signature_required" : true
  }
}

Sample Response:

{
  "id" : 152040,
  "reference_id" : "ABCDEFG12345",
  "state" : "scheduled",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
    "signature_required" : true
  },
  "tracking_number" : "RETHNKW354W3H438",
  "created_at" : "2017-12-25T06:00:00-06:00",
  "updated_at" : "2017-12-25T06:00:00-06:00"
}
Name Type Description
reference_id (required) string The user supplied ID for the shipment. Max length 100 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.
deliver_between
(required)
TimeWindow The window within which the shipment must be completed.
options
(required)
DeliveryOptions Any delivery options for the shipment.

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",
  "state" : "delivered",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
    "signature_required" : true
  },
  "tracking_number" : "RETHNKW354W3H438",
  "created_at" : "2017-12-25T06:00:00-06:00",
  "updated_at" : "2017-12-25T06:00:00-06:00"
}

Update a Shipment

Parameters

Sample Request:

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

{
  "reference_id" : "ABCDEFG12345",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
    "signature_required" : true
  }
}

Sample Response:

{
  "id" : 152040,
  "reference_id" : "ABCDEFG12345",
  "state" : "scheduled",
  "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",
      "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",
      "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:00-06:00",
  "deliver_between" : {
    "start" : "2017-12-26T06:00:00-06:00",
    "end" : "2017-12-26T20:00:00-06:00"
  },
  "options" : {
    "signature_required" : true
  },
  "tracking_number" : "RETHNKW354W3H438",
  "created_at" : "2017-12-25T06:00:00-06:00",
  "updated_at" : "2017-12-25T06:00:00-06:00"
}
Name Type Description
reference_id string The user supplied ID for the shipment.
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.

Cancel a Shipment

Sample Request:

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

A Shipment can be canceled at any time up until driver has confirmed pickup.

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.
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.

Fields

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

Address

Represents an address.

Fields

Name Type Description
name string The name. This helpful for the driver if the location is a business. Max length 200 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.

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 boolean

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.

Webhooks

Sample webhook payload:

{
  "event" : "shipment.driver_assigned",
  "sent_at" : "2018-01-14T19:20+01:00",
  "data" : {
    "id" : 5678,
    "occurred_at" : "2018-01-14T19:20+01:00",
    "driver" : {
      "name" : "Beth Johnson",
      "phone" : "7701234567"
    }
  }
}

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

Name Description
driver_assigned A driver has been assigned to the shipment.
pickup_confirmed The driver has successfully pickup up the shipment, and is headed to the delivery location.
delivery_confirmed The driver has successfully delivered the shipment.
delivery_attempted The driver was unsuccessful in delivering the shipment.
return_created A return shipment has been created.
canceled The shipment was canceled.
expired The shipment has expired.

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.