Our API documentation is designed to be used as a guide for integrating your system directly into MachShip.
This documentation describes the technical details of dealing with MachShip’s API layer, the security requirements and provides links to further API definition documentation.
The current API is currently version 2 and all our documentation relates to this version of the API.
All MachShip's functionality is available via the API, however, we have documented a subset of the most commonly used functions with MachShip. If you require further documentation on functionality that is not currently documented, please email the MachShip team at firstname.lastname@example.org
MachShip API Introduction
MachShip provides a fully featured, first class RESTful API layer using well-defined JSON objects. All requests to MachShip are either a POST or a GET which is documented in our API technical documentation.
The API layer can only be communicated via HTTPS over SSL.
All API calls require a valid API token which is described below.
Testing vs Live Environment
There are two versions of MachShip running:
MachShip provides a testing/demonstration environment (demo.machship.com) which we highly recommend using when integrating with MachShip. This environment is completely sandboxed which means that it will not book or manifest consignments to the carriers and will not send any emails, text messages or issue any external API calls to carriers and other external systems.
Once you have completed your integration and are ready to integrate with the live environment, update your API URLs to live.machship.com and update your API token to your live API token.
In the live environment, if you manifest consignments or create a consignment for some carriers, this will create a live consignment in the carrier's system and you will need to cancel that consignment directly with the carrier and/or the account owner. You should always use our demo environment to test your API integration.
Authentication with MachShip
All requests to MachShip require a valid API token. This token can be generated by logging in to MachShip and adding a new token to your user. Our authentication uses a bearer token to authenticate the caller and must be provided on each request to MachShip. This bearer token must be added as a header like so:
The demo and live environments do not use the same tokens and the same token will not work between the 2 environments. We provide a ping endpoint which you can use to test that your token is valid. If it returns a 200 and object = true, then you have successfully authenticated with MachShip.
POST https://demo.machship.com/apiv2/authenticate/ping HTTP/1.1
Successful Ping Response:
If you are receiving a 401 Unauthorized response, please check the following:
- You have correctly entered your API token as a header with the token as the key
- You are using the correct token for the right environment. For example, are you using a demo token against the live environment?
- Contact the API token issuer to check that the token is still valid
Our online API definition documentation can be found at https://demo.machship.com/swagger.
If you click the Authorize button at the top of the page and enter your API token, you can then call MachShip’s API directly from within this documentation. This allows you to test your API calls and JSON objects directly through the browser. Examples of the objects in both the requests and responses can be found in this API help documentation.
Questions and API Help
If you have any questions regarding the API or you are after additional documentation, please email the MachShip team at email@example.com