NAV
shell

Introduction

{
  "message": "Hello World!",
  "description": "Currently all examples are shown as simple cURL statements, however as we continue to push out SDK's the tabs above will represent the examples you would like to see.",
  "version": "0.3.0-alpha1",
  "built_with_love": "But please feel free to make suggestions to our documentation!"
}

Welcome to the Montway API Documentation. You can utilize our API to access Montway API endpoints, which can allow for the full functionality of vehicle lookup, quote creation and quote booking.

Currently Montway’s API v1 supports the HTTP protocol.

Staging endpoint: https://gateway-staging.montway.com/

Production endpoint: https://gateway.montway.com/

Authentication

OAuth2 Token (sent in header)

curl -H "Authorization: Bearer [ACCESS TOKEN]" https://gateway.montway.com

OAuth2 Token (sent as a paramater)

curl https://gateway.montway.com/?access_token=[ACCESS TOKEN]

Prior to using this API a new OAuth2 client application must be registered within the Montway B2B Platform.

All developers need to register their application before getting started. A registered OAuth2 application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared. A personal access token will be given to you during your OAuth2 handshake process, all future requests will be made with the provided access token.

Montway’s OAuth implementation supports the standard authorization client credentials grant type. Developers should implement the web application flow described below to obtain an authentication code and then exchange it for a token.

Authorization: Bearer [ACCESS TOKEN]

OAuth2 Authentication Flow

Request

curl -u Iez3IeFiv:1fc854110e553800esh0uc3ieThi7chaeLengah -X POST -H "Content-Type: application/json" -d
  '{
     "grant_type": "client_credentials",
   }' https://gateway.montway.com/login/oauth/access_token

Response

{
  "access_token": "83105a3ec6657a3ced07a450b1b9590ad6f7bed7",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "get_status create_quotes create_v2_quotes update_v2_quotes get_v2_quotes get_quotes update_quotes book_v2_quotes",
  "refresh_token": "7e32256645abe96bbf4ffeee53bdfdcb264671de"
}

Currently the standard OAuth2 flow is not supported! Every Client ID is associated with an actual platform user that may or may not have the whole set of permissions opening the whole functionality. In the future this will be a subject to change so stay tuned.

If the user accepts your request, Montway redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

Exchange this for an access token:

POST https://gateway.montway.com/login/oauth/access_token

Headers

Name Type Description
Authorization string Basic Authorization is being used.
Example header would be
Basic YWUwYWZjMTM3OjRmZmNhZDNjNWMyOThlYmFjMzdlYWQwZDdiOWRkMzFmNTNiN2UwZDc=.
Encoding algorithm is Base64(client_id:client_secret)
Content-Type string Please use “application/json”

Parameters

Name Type Description
grant_type string Please use the string ‘client_credentials’

Response

Name Type Description
access_token string The ACCESS TOKEN
expires_in integer Expiration time interval
token_type string By default “Bearer”
scope string Available scopes separates by space characters
refresh_token string The REFRESH TOKEN

Common Errors for the Access Token Request

The format of these responses is determined by the accept header you pass. The following examples only show JSON responses.

Missing grant type

Missing grant type response

{
  "error": "invalid_request",
  "error_description": "The grant type was not specified in the request"
}

If the grant_type is missing you will receive this error response.

To solve this error, go back and supply the grant_type as client_credentials

Unsupported grant type

Unsupported grant type response

{
  "error": "unsupported_grant_type",
  "error_description": "Grant type \"client_credential\" not supported"
}

In case the grant type you are supplying as unsupported you will get an error message saying exactly that.

To solve this error, go back and supply the grant_type as client_credentials

Incorrect / Missing client credentials

Incorrect / Missing client credentials response

{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}

If the client_id and/or client_secret you pass are incorrect you will receive this error response.

To solve this error, go back and make sure you have the correct credentials for your oauth application. Double check the client_id and client_secret to make sure they are correct and being passed correctly to the particular API endpoint.

Supplying an expired access token to a request

Expired access token response

{
  "error": "invalid_token",
  "error_description": "The access token provided has expired"
}

To solve this error, generate another access token and retry your request wuth the newly generated [ACCESS TOKEN].

Quotes

The quote service is here to help calculate what it will cost to move one or more vehicles from the origin address to the destination address.

Creation of a Quote

Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer [ACCESS TOKEN]" -d '{
  "transport": {
    "origin_location": "Boca Raton, FL 33487",
    "destination_location": "Chicago, IL 60654",
    "trailer_type": "OPEN"
  },
  "vehicle": {
    "make": "Tesla",
    "model": "Model S",
    "year": 2016,
    "condition": "running"
  ],
  "__meta__": {
    "transition_to": {
      "path": "/complete"
    }
  }
}' https://gateway.montway.com/v1/quote

Response

{
  "quote_id": "F5B3C09F5E85981B",
  "quote_ref_id": "456456",
  "expires_at": "2016-03-26T17:04:46+0000",
  "transit_time": {
    "min": 4,
    "max": 8,
    "short_label": "4 - 8 days",
    "label": "Transit time: 4 - 8 days"
  },
  "vehicle": {
    "make": "Tesla",
    "model": "Model S",
    "year": 2016,
    "condition": "running"
  },
  "rates": {
    "two_day_pickup": {
      "type": "regular",
      "price": 2000
    },
    "four_day_pickup": {
      "type": "regular",
      "price": 1739
    },
    "seven_day_pickup": {
      "type": "regular",
      "price": 1639
    },
    "ten_day_pickup": {
      "type": "regular",
      "price": 1599
    }
  }
}

The creation of a quote is just that, a quote object is created, however this does not mean that the quote was booked and processed. Please refer to the Booking API for details on how to complete an order.

Endpoint

POST https://gateway.montway.com/v1/quote

Success Status Code

201 Created

Request Parameters

Name Type Description
transport object Contains the origin_location, destination_location and trailer_type of the shipment
vehicle object Vehicle object, containing the following properties make, model, condition and year
__meta__ object Can contain any state you would like and will be returned on the response object

Both the origin_location and the destination_location have three required fields:

You may pass these as a string Boca Raton, FL 33487

Validation Rules

Name Type Description
transport.origin_location string Required field, describing exactly any existing location in the specified format. There are locations that are not under service and for those the API will respond accordingly.
transport.destination_location string Required field, describing exactly any existing location in the specified format. There are locations that are not under service and for those the API will respond accordingly.
transport.trailer_type enum Optional field (defaults to OPEN), must be one of the following: OPEN, ENCLOSED (case-insensitive)
vehicle.make string Required field, must be one of the vehicle makes supplied by the /v1/vehicles endpoint
vehicle.model string Required field, must be one of the vehicle models for the specified make supplied by the /v1/vehicles endpoint
vehicle.year int Required field, must be an integer
vehicle.condition enum Optional field (defaults to ‘RUNNING’), must be one of the following: RUNNING, NONRUNNING (case-insensitive)

Response Parameters

Name Type Description
quote_id string This is the id of your quote for future utilization, you will want to utilize this id during the booking process.
quote_ref_id string This is the id of your quote as represented in the B2B Platform for agent usage. Currently it is available for utilization in the API
expires_at string Datetime string when the quote is going to expire
transit_time object Contains min, max, short_label, label
vehicle object Contains vehicle make, model, year, condition
rates object Contains a list of charges which include two_day_pickup, four_day_pickup, seven_day_pickup, ten_day_pickup

Fetch a Quote

Request

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer [ACCESS TOKEN]" https://gateway.montway.com/v1/quote/F5B3C09F5E85981B

Response

{
  "quote_id": "F5B3C09F5E85981B",
  "quote_ref_id": "456456",
  "expires_at": "2016-03-26T17:04:46+0000",
  "transit_time": {
    "min": 4,
    "max": 8,
    "short_label": "4 - 8 days",
    "label": "Transit time: 4 - 8 days"
  },
  "vehicle": {
    "make": "Tesla",
    "model": "Model S",
    "year": 2016,
    "condition": "running"
  },
  "rates": {
    "two_day_pickup": {
      "type": "regular",
      "price": 2000
    },
    "four_day_pickup": {
      "type": "regular",
      "price": 1739
    },
    "seven_day_pickup": {
      "type": "regular",
      "price": 1639
    },
    "ten_day_pickup": {
      "type": "regular",
      "price": 1599
    }
  }
}

The process of fetching a quote is a pretty trivial process, the only required field we need here is the quote_id which could be actually specified either as formerly received quote_id or quote_ref_id.

Endpoint

GET https://gateway.montway.com/v1/quote/:quote_id

Response Parameters

Name Type Description
quote_id string This is the id of your quote for future utilization, you will want to utilize this id during the booking process.
quote_ref_id string This is the id of your quote as represented in the B2B Platform for agent usage. Currently it is available for utilization in the API
expires_at string Datetime string when the quote is going to expire
transit_time object Contains min, max, short_label, label
vehicle object Contains vehicle make, model, year and condition
rates object Contains a list of charges which include two_day_pickup, four_day_pickup, seven_day_pickup and ten_day_pickup

Recalculate a Quote

Request

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer [ACCESS TOKEN]" -d '{
  "original_quote_id": "F5B3C09F5E85981B".
  "transport": {
    "origin_location": "Boca Raton, FL 33487",
    "destination_location": "Chicago, IL 60654",
    "trailer_type": "OPEN"
  },
  "vehicle": {
    "make": "Tesla",
    "model": "Model S",
    "year": 2016,
    "condition": "running"
  },
  "__meta__": {
    "transition_to": {
      "path": "/complete"
    }
  }
}' https://gateway.montway.com/v1/quote/F5B3C09F5E85981B

Response

{
  "quote_id": "F5B3C09F5E85981B",
  "quote_ref_id": "456456",
  "expires_at": "2016-03-26T17:04:46+0000",
  "transit_time": {
    "min": 4,
    "max": 8,
    "short_label": "4 - 8 days",
    "label": "Transit time: 4 - 8 days"
  },
  "vehicle": {
    "make": "Tesla",
    "model": "Model S",
    "year": 2016,
    "condition": "running"
  },
  "rates": {
    "two_day_pickup": {
      "type": "regular",
      "price": 2000
    },
    "four_day_pickup": {
      "type": "regular",
      "price": 1739
    },
    "seven_day_pickup": {
      "type": "regular",
      "price": 1639
    },
    "ten_day_pickup": {
      "type": "regular",
      "price": 1599
    }
  }
}

The process of updating a quote is a pretty trivial process, the only required field we need here is the original quote_id which will acts as the primary key to update.

Endpoint

PUT https://gateway.montway.com/v1/quote/:quote_id

Name Type Description
transport object Contains the origin_location, destination_location and trailer_type of the shipment
vehicle object Vehicle object, containing the following properties make, model, condition and year
__meta__ object Can contain any state you would like and will be returned on the response object

Validation Rules

Validation rules are the same as for Creation of a Quote

Response Parameters

Name Type Description
quote_id string This is the id of your quote for future utilization, you will want to utilize this id during the booking process.
quote_ref_id string This is the id of your quote as represented in the B2B Platform for agent usage. Currently it is available for utilization in the API
expires_at string Datetime string when the quote is going to expire
transit_time object Contains min, max, short_label, label
vehicle object Contains vehicle make, model, year and condition
rates object Contains a list of charges which include two_day_pickup, four_day_pickup, seven_day_pickup and ten_day_pickup

Response Errors

Response Errors

{
  "errors": [
    {
      "logref": "transport",
      "error_message": "Origin Location cannot be blank."
    },
    {
      "logref": "transport",
      "error_message": "Destination Location cannot be blank."
    },
    {
      "logref": "general",
      "error_message": "Not valid trailer type supplied!"
    },
    {
      "logref": "vehicle",
      "error_message": "Please enter valid vehicle make"
    },
    {
      "logref": "vehicle",
      "error_message": "Unable to find valid mapping for the provided vehicles."
    },
    {
      "logref": "general",
      "error_message": "Unable to determine the vehicles passed along with the calculation!"
    },
    {
      "logref": "general",
      "error_message": "Vehicle Year must be a number."
    },
    {
      "logref": "general",
      "error_message": "We could not determine one of the locations specified."
    }
  ]
}

The following errors may be returned to help better understand why the quote could not be created. This is not an extensive list of all possible error messages but a sample.

Name Type Description
errors list Holds multiple objects the point out the exact error preventing the quote creation / recalculation
errors[].logref string Single pointer to the problem
errors[].error_message string A detailed message consisting of why the quote could not be created

Booking

Completing Your order

Booking Request

curl -X POST -H "Authorization: Bearer [ACCESS TOKEN]" -d '{
  "quote_id": "806731AA4A48C4D3",
  "rate_type": "four_day_pickup",
  "pickup_date": "2012-12-12",
  "customer": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number": "3121231234",
    "email_address": "john.smith@example.com"
  },
  "pickup": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number":"(123) 232-1321",
    "mobile_number":"(123) 232-1321",
    "work_number":"(123) 232-1321",
    "street_address": "1st street"
  },
  "delivery": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number":"(123) 232-1321",
    "mobile_number":"(123) 232-1321",
    "work_number":"(123) 232-1321",
    "street_address": "1st street"
  }
}' https://gateway.montway.com/v1/book

Booking Response

{
  "order_id": "01CB998DB5745EB5",
  "order_ref_id": "123123",
  "quote_id": "01CB998DB5745EB5",
  "quote_ref_id": "456456"
}

Booking a quote with the Booking API layer is very straight-forward to utilize.

When booking a vehicle you will remember from the Quote Services response that there were several options regarding the rates which have two_day_pickup, four_day_pickup, seven_day_pickup and no_load_window as nested objects.

Endpoint

POST https://gateway.montway.com/v1/book

Success Status Code

201 Created

Request Parameters

Name Type Description
quote_id string This is the Quote ID that you should be holding onto from the Quote Creation response object
customer object Contains the first_name, last_name, phone_number and email_address of the customer
pickup object Contains the first_name, last_name, phone_number, mobile_number, work_number and street_address of the pickup contact
delivery object Contains the first_name, last_name, phone_number, mobile_number, work_number and street_address of the delivery contact
rate_type string This is an enumeration of types, you may choose only one option from the available in the given quote
pickup_date string This is the first available pick date in ‘YYYY-MM-DD’ format

Booking Request with a registration number

curl -X POST -H "Authorization: Bearer [ACCESS TOKEN]" -d '{
  "quote_id": "806731AA4A48C4D3",
  "rate_type": "four_day_pickup",
  "registration_number": "1231232",
  "pickup_date": "2016-12-18",
  "customer": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number": "3121231234",
    "email_address": "john.smith@example.com"
  },
  "pickup": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number":"(123) 232-1321",
    "mobile_number":"(123) 232-1321",
    "work_number":"(123) 232-1321",
    "street_address": "1st street"
  },
  "delivery": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number":"(123) 232-1321",
    "mobile_number":"(123) 232-1321",
    "work_number":"(123) 232-1321",
    "street_address": "1st street"
  }
}' https://gateway.montway.com/v1/book

Booking Response

{
  "order_id": "01CB998DB5745EB5",
  "order_ref_id": "123123",
  "quote_id": "01CB998DB5745EB5",
  "quote_ref_id": "456456"
}
Name Type Description
registration_number string Unique internal registration mumber, id, etc… to be passed to Montway API.

Validation Rules

Name Type Description
quote_id string Required field, must be the quote_id coming from the Create A Quote request. It must be valid, exisitng, not expired (expiration date in the quote response) and not booked yet.
rate_type string Required field, must be one if the rate options coming from the Create A Quote request.
pickup_date string Required field, must be a date string in the following format: YYYY-MM-DD. We do not allow weekends and national holidays - New Year’s Day, Martin Luther King Day, Presidents’ Day, Memorial Day, Independence Day, Labor Day, Columbus Day, Veterans Day, Thanksgiving Day, Christmas Day, Christmas Day observed.
registration_number string Depending on your setup this could be required or optional field.
customer.first_name string Required field, at least 2 characters and maximum 24 characters.
customer.last_name string Required field, at least 2 characters and maximum 24 characters.
customer.phone_number string Required field. US number that contains 10 digits.
customer.email_address string Optional field. Must be a valid email address.
pickup.first_name string Required field, at least 2 characters and maximum 24 characters.
pickup.last_name string Required field, at least 2 characters and maximum 24 characters.
pickup.phone_number string Required field. US number that contains 10 digits.
pickup.mobile_number string Optional field. US number that contains 10 digits.
pickup.work_number string Optional field. US number that contains 10 digits.
pickup.street_address string Required field. Max length of 100 characters.
delivery.first_name string Required field, at least 2 characters and maximum 24 characters.
delivery.last_name string Required field, at least 2 characters and maximum 24 characters.
delivery.phone_number string Required field. US number that contains 10 digits.
delivery.mobile_number string Optional field. US number that contains 10 digits.
delivery.work_number string Optional field. US number that contains 10 digits.
delivery.street_address string Required field. Max length of 100 characters.

Response Parameters

Name Type Description
order_id string This is the unique id of your completed order
order_ref_id string This is the unique id of your completed order as it would be represented in the B2B Platform
quote_id string This is the quote that your order is based off, this quote_id is what came from the request
quote_ref_id string This is the unique id of your booked quote as it is be represented in the B2B Platform

Response Errors

Response Errors

{
  "errors": [
    {
      "logref": "general",
      "error_message": "Unable to find quote with identity #806731AA4A48C4D3."
    },
    {
      "logref": "quote_id",
      "error_message": "Provided quote identity is already booked!"
    },
    {
      "logref": "pickup_date",
      "error_message": "Pickup Date cannot be blank."
    },
    {
      "logref": "rate_type",
      "error_message": "Missing desired pickup option window information!"
    },
    {
      "logref": "customer",
      "error_message": "Please enter your full name e.g. John Smith."
    },
    {
      "logref": "customer",
      "error_message": "Please enter a valid Phone."
    },
    {
      "logref": "customer",
      "error_message": "Email is not a valid email address."
    },
    {
      "logref": "pickup",
      "error_message": "Street Address cannot be blank."
    },
    {
      "logref": "delivery",
      "error_message": "Street Address is too long (maximum is 100 characters)."
    }
  ]
}

The following errors may be returned to help better understand why the quote could not be booked. This is not an extensive list of all possible error messages but a sample.

Name Type Description
errors list Holds multiple objects the point out the exact error preventing the quote booking
errors[].logref string Single pointer to the problem
errors[].error_message string A detailed message consisting of why the quote could not be booked

Vehicles

Retrieving All Vehicles

Request all vehicles

curl -X GET -H "Accept: application/json" -H "Authorization: Bearer [ACCESS TOKEN]"    https://gateway.montway.com/v1/vehicles

This solution is best used if you require a device to go offline and have access to all vehicle information or would like to use our service to update a local caching / Elastic Search layer.

Endpoint

GET https://gateway.montway.com/v1/vehicles

Response

{
  "vehicles": [
    {
      "vehicle_unique": "acura",
      "vehicle_label": "Acura",
      "models": [
        {
          "model_unique": "cl",
          "model_label": "CL"
        },
        {
          "model_unique": "vigor",
          "model_label": "Vigor"
        }
      ]
    },
    {
      "vehicle_unique": "......"
    }
  ]
}

Response Parameters

Name Type Description
last_time_updated string This is a UTC timestamp of the last time we have updated our internal vehicle store
vehicles list This list contains all vehicles, each vehicle make is return in an object with a nested models property which includes all the models of the manufacture.
vehicles[].vehicle_unique string Unique identifier in a safe string format of make in snake_case
vehicles[].vehicle_label string A human readable version of the car manufacturer
vehicles[].models list This list contains all models for the current vehicle.
vehicles[].models[].model_unique string Unique identifier in a safe string format of model in snake_case
vehicles[].models[].model_label string A human readable version of the car model

Push Services

Vehicle Push Services

Quote & Booking Streams

Status Push Services

Status

Basic Status

curl -H "Content-Type: application/json" https://gateway.montway.com/v1/status

{
  "status": "green",
  "time_stamp": "1450298006"
}

The status of all services can be accessed via this endpoint.

This endpoint does not require authentication, however this endpoint is rate limited so please do not attempt to long poll this endpoint on intervals quicker than 1000ms.

If you require realtime status of the API, please see our Push Services section for more information on RTC / socket communication.

Endpoint

GET https://gateway.montway.com/v1/status

Response Types

Name Type Description
status string The current status of Montway API Services, can be green, amber, red
time_stamp string Current UTC time of request

Errors

API Response Errors

Let’s ping status 100 times in one ms!

curl -X GET -H "Content-Type: application/json" https://gateway.montway.com/v1/status

The service will tell you exactly why you must stop

{
  "response_type": "error",
  "response_code": "429",
  "description": "You're requesting too quickly, rate limiting has activated.",
  "__meta__": {
    "_link": "https://gateway.montway.com/developer/errors/429",
    "_resource": "Status Services",
    "_action": "Please wait 1000ms and try again"
  }
}

No cryptic guessing here! All API responses are straight forward, if an error ever occurs you will receive a predictable error format, this is uniform across all requests.

The headers will be proper, we are not going to return 500 on an authentication error, we hate working with horrible API’s too! Let’s take for example something as simple as pinging the Montway API Status Service

Response Parameters

Name Type Description
response_type string This tells you what the response is, currently you will only receive a type of error
response_code string The code returned a standard HTTP error code, please see the table below for a list of error codes that we support, you will never receive an error that is not documented below.
description string Short description of the error code, no one wants to constantly google what 418 is.
_link string A hyperlink that points to the error description
_resource string Where did the error originate from?
_action string A recommendation of your next course of action

The Montway API v1 uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is incorrect
401 Unauthorized – Your [ACCESS TOKEN] is incorrect
403 Forbidden – The resource requested is for authenticated users only
404 Not Found – The specified resource could not be found
409 Conflict – The request could not be validated
410 Gone – The resource requested has been removed from our servers
500 Internal Server Error – We had a problem with our server. Please try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
shell