Skip links
+1(630) 300 1501
EasyLoad

Developers & API

We’re ready to help with your integration. Contact us to discuss any topics and questions. We will set up a dedicated Slack channel to communicate with you in real-time.

Show Topics

Overview

The API has been designed to allow partners of Super Dispatch to share information back and forth between two [or more] systems. Our RESTful API allows an order to be sent through Super Dispatch, to be fulfilled using Super Dispatch’s Mobile app and Dashboard [TMS], while allowing other [select] systems to receive requested updates during the order’s lifecycle. Key handshakes:

  • send order to a carrier via Super Dispatch mobile application
  • receive a confirmation
  • vehicle inspection
  • order tracking
  • proof of delivery (ePOD)
  • bill of lading (eBOL)

Requirements

These requirements should be met when sending a request:

  • Use only https connection.
  • We use REST for communications.
  • We use Webhook to notify about order status updates.
  • For all requests and responses we use application/json as a content type.
  • Cross-origin resource sharing is enabled by default.
  • We DO NOT recommend long-polling the API. The API is rate limited. Please contact us if you need to long-poll any API endpoint.

Terminology

General Terms

  • Broker: An intermediary who arranges transactions between a buyer and a seller.
  • Carrier: a transportation company that owns one or multiple trucks.
  • Owner Operator: a company/professional who owns and operates their business with a single truck.
  • Fleet: a company that runs and manages a group of trucks.
  • Driver: a truck driver who is responsible for shipping vehicles.
  • Vehicle: a single vehicle (usually associated with a specific VIN).
  • BOL (Bill of Lading): a document that describes inspection details of a particular vehicle.

Order States

  • Unassigned: an order is not assigned to a driver.
  • Assigned: an order is assigned to a driver.
  • Picked Up: an order is picked up by a driver from an origin.
  • In Transit: an order is on its way.
  • Delivered: an order is delivered by a driver to a destination.
  • Archived: an order is archived.
  • Billed: an order has been invoiced to a customer.
  • Paid: a payment for the order has been received by a customer.

Base URL

Production Environment

<https://carrier.superdispatch.com/v1>

Staging Environment

<https://staging.carrier.superdispatch.org/v1>

Responses

The API always returns 200 OK for all requests that are handled by our server. A response content always has the meta section that contains additional details of the response:

{
  "meta": {
    "code": <integer>, // HTTP Status Code
    "request_id": <string> // Request ID generated for each request by the API
  },
  ...
}

Status Codes

  • Success: 200 , 201, 204
  • Failure: 400 , 401 , 403 , 404 , 405 , 409 , 415 , 429

Success Responses

Collection Response:

{
  "data": [
    // An array of items
  ],
  "meta": {
    "code": <integer>,
    "request_id": <string>
  },
  "pagination": {
    "previous": <string>, // A link to request for previous items
    "next": <string> // A link to request for next items
  }
}

Single Response:

{
  "data": {
    // A single item
  },
  "meta": {
    "code": <integer>,
    "request_id": <string>
  }
}

Deleted Response:

{
  "meta": {
    "code": <integer>,
    "request_id": <string>
  }
}

Error Response

{
  "error": {
    "message": <string>,
    "context": {
      <field_name>: [
        // An array of field error messages
      ]
    }
  },
  "meta": {
    "code": <integer>,
    "request_id": <string>
  }
}

Authentication

The API supports the OAuth 2 Client Credentials grant type. An API client should get access_token by sending an authentication request with client_id and client_secret .

Request:

// Production
POST <https://carrier.superdispatch.com/oauth/token/>
// Development
POST <https://staging.carrier.superdispatch.org/oauth/token/>

Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Response:

{
  "scope": <string>,
  "access_token": <string>,
  "token_type": <string>, // E.g. Bearer
  "expires_in": <integer> // In seconds
}

All requests to secured endpoints must be sent with the Authorization header:

Authorization: Bearer <access_token>

Resource Endpoints

Drivers

Create a Driver

Request:

POST <base_url>/carriers/{id}/drivers/
Content-Type: application/json

{
  "name": <string>,
  "email": <string>,
  "phone": <string>,
  "truck_capacity": <integer>
}

Response:

{
  "data": {
    "id": <integer>, // Super Dispatch Driver ID
    "name": <string>,
    "email": <string>,
    "phone": <string>,
    "truck_capacity": <integer>
  },
  "meta": {
    "code": 201,
    "request_id": <string>
  }
}

Update a Driver

Request:

PUT/PATCH <base_url>/drivers/{id}/
Content-Type: application/json

{
  "name": <string>,
  "email": <string>,
  "phone": <string>,
  "truck_capacity": <integer>
}

Response:

{
  "data": {
    "id": <integer>, // Super Dispatch Driver ID
    "name": <string>,
    "email": <string>,
    "phone": <string>,
    "truck_capacity": <integer>
  },
  "meta": {
    "code": 200,
    "request_id": <string>
  }
}

Orders

Create an Order

Request:

POST <base_url>/orders/
Content-Type: application/json

{
  "driver_id": <integer>, // Super Dispatch Driver ID (Optional)
  "number": <string>, // Order Number
  "price": <decimal>,
  "buyer_number": <string>,
  "broker_fee": <decimal>,
  "instructions": <string>, // Instructions
	"inspection_type": <string>, // Possible values: "aiag", "standard", and "advanced"
  "payment": {
    "terms": <string>, // Payment Terms: see the Attributes section
    "notes": <string> // maximum 1000 characters
  },
  "customer": {
    "name": <string>,
    "address": <string>,
    "city": <string>,
    "state": <string>,
    "zip": <string>,
    "contact": {
      "name": <string>,
      "phone": <string>,
      "email": <string>,
      "fax": <string>
    }
  },
  "pickup": {
    "scheduled_at": <datetime>,
    "venue": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>
      }
    }
  },
  "delivery": {
    "scheduled_at": <datetime>,
    "venue": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>
      }
    }
  },
  "vehicles": [ // Optional (Only allowed for POST)
    {
      "make": <string>,
      "model": <string>,
      "year": <integer>,
      "color": <string>,
      "vin": <string>,
      "type": <string>, // Vehicle Type: see the Attributes section
      "lot_number": <string>, // Optional
      "is_inoperable": <boolean>,
      "requires_enclosed_trailer": <boolean>
    },
    ...
  ]
}

Response:

{
  "data": {
    "id": <integer>, // Super Dispatch Order ID
    "number": <string>, // Order Number
    "price": <decimal>,
    "buyer_number": <string>,
    "broker_fee": <decimal>,
    "instructions": <string>, // Instructions
    "status": <string>, // Order Status: see the Attributes section
	  "inspection_type": <string>, // Possible values: "aiag", "standard", and "advanced"
    "payment": {
      "terms": <string>, // Payment Terms: see the Attributes section
      "notes": <string> // maximum 1000 characters
    },
    "customer": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>,
        "email": <string>,
        "fax": <string>
      }
    },
    "pickup": {
      "scheduled_at": <datetime>,
      "completed_at": <datetime>,
      "venue": {
        "name": <string>,
        "address": <string>,
        "city": <string>,
        "state": <string>,
        "zip": <string>,
        "contact": {
          "name": <string>,
          "phone": <string>
        }
      }
    },
    "delivery": {
      "scheduled_at": <datetime>,
      "completed_at": <datetime>,
      "venue": {
        "name": <string>,
        "address": <string>,
        "city": <string>,
        "state": <string>,
        "zip": <string>,
        "contact": {
          "name": <string>,
          "phone": <string>
        }
      }
    },
    "vehicles": [
      {
        "id": <integer>, // Super Dispatch Vehicle ID
        "make": <string>,
        "model": <string>,
        "year": <integer>,
        "color": <string>,
        "vin": <string>,
        "type": <string>, // Vehicle Type: see the Attributes section
        "lot_number": <string>,
        "is_inoperable": <boolean>,
        "requires_enclosed_trailer": <boolean>
      },
      ...
    ],
    "carrier": {
      "id": <integer>, // Super Dispatch Carrier ID
      "name": <string>, // Company Name
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "mc_number": <string>, // MC Number
      "us_dot_number": <string>, // US DOT Number
      "number_of_trucks": <integer>,
      "contact": {
        "name": <string>,
        "phone": <string>,
        "email": <string>,
        "fax": <string>
      },
      "driver": {
        "id": <integer>, // Super Dispatch Driver ID
        "name": <string>,
        "email": <string>,
        "phone": <string>,
        "truck_capacity": <integer>
      }
    }
  },
  "meta": {
    "code": 201,
    "request_id": <string>
  }
}

Update an Order

Request:

PUT/PATCH <base_url>/orders/{id}/
Content-Type: application/json

{
  "driver_id": <integer>, // Super Dispatch Driver ID (Optional)
  "number": <string>, // Order Number
  "price": <decimal>,
  "buyer_number": <string>,
  "broker_fee": <decimal>,
  "instructions": <string>, // Instructions
	"inspection_type": <string>, // Possible values: "aiag", "standard", and "advanced"
  "payment": {
    "terms": <string>, // Payment Terms: see the Attributes section
    "notes": <string> // maximum 1000 characters
  },
  "customer": {
    "name": <string>,
    "address": <string>,
    "city": <string>,
    "state": <string>,
    "zip": <string>,
    "contact": {
      "name": <string>,
      "phone": <string>,
      "email": <string>,
      "fax": <string>
    }
  },
  "pickup": {
    "scheduled_at": <datetime>,
    "venue": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>
      }
    }
  },
  "delivery": {
    "scheduled_at": <datetime>,
    "venue": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>
      }
    }
  }
}

Response:

{
  "data": {
    "id": <integer>, // Super Dispatch Order ID
    "number": <string>, // Order Number
    "price": <decimal>,
    "buyer_number": <string>,
    "broker_fee": <decimal>,
    "instructions": <string>, // Instructions
	  "inspection_type": <string>, // Possible values: "aiag", "standard", and "advanced"
    "status": <string>, // Order Status: see the Attributes section
    "payment": {
      "terms": <string>, // Payment Terms: see the Attributes section
      "notes": <string> // maximum 1000 characters
    },
    "customer": {
      "name": <string>,
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "contact": {
        "name": <string>,
        "phone": <string>,
        "email": <string>,
        "fax": <string>
      }
    },
    "pickup": {
      "scheduled_at": <datetime>,
      "completed_at": <datetime>,
      "venue": {
        "name": <string>,
        "address": <string>,
        "city": <string>,
        "state": <string>,
        "zip": <string>,
        "contact": {
          "name": <string>,
          "phone": <string>
        }
      }
    },
    "delivery": {
      "scheduled_at": <datetime>,
      "completed_at": <datetime>,
      "venue": {
        "name": <string>,
        "address": <string>,
        "city": <string>,
        "state": <string>,
        "zip": <string>,
        "contact": {
          "name": <string>,
          "phone": <string>
        }
      }
    },
    "vehicles": [
      {
        "id": <integer>, // Super Dispatch Vehicle ID
        "make": <string>,
        "model": <string>,
        "year": <integer>,
        "color": <string>,
        "vin": <string>,
        "type": <string>, // Vehicle Type: see the Attributes section
        "lot_number": <string>,
        "is_inoperable": <boolean>,
        "requires_enclosed_trailer": <boolean>
      },
      ...
    ],
    "carrier": {
      "id": <integer>, // Super Dispatch Carrier ID
      "name": <string>, // Company Name
      "address": <string>,
      "city": <string>,
      "state": <string>,
      "zip": <string>,
      "mc_number": <string>, // MC Number
      "us_dot_number": <string>, // US DOT Number
      "number_of_trucks": <integer>,
      "contact": {
        "name": <string>,
        "phone": <string>,
        "email": <string>,
        "fax": <string>
      },
      "driver": {
        "id": <integer>, // Super Dispatch Driver ID
        "name": <string>,
        "email": <string>,
        "phone": <string>,
        "truck_capacity": <integer>
      }
    }
  },
  "meta": {
    "code": 200,
    "request_id": <string>
  }
}
🍪 This website uses cookies to improve your web experience.