API introduction and authentication

API introduction and authentication

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 support@machship.com

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 Mode

MachShip provides a testing mode which can be utilized when training a new user or testing an integration. This mode is completely sandboxed which means that it will not issue any external API calls to carriers but will show you exactly how MachShip would work under those circumstances.

To learn more about the test environment. Please go to this link.

In order to generate a Test API user, you will first need to create a user in Test mode where you will also be able to generate an API token.

To learn on how to create test API user, click on this link.

Once you are ready to use the live environment, you can update your user to stop them from being in test mode. This will allow a user to see and create live consignments and manifest them.

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 token to authenticate the caller and must be provided on each request to MachShip. This token must be added as a header like so:

token: <api_token>

If you created a Test API user and generated an API token, it will be the same API token you will use when you decide to stop your user from being in test mode. There is no need to regenerate a new API token.

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.

Ping Request:

POST https://live.machship.com/apiv2/authenticate/ping HTTP/1.1
Host: live.machship.com
token: <api_token>

Successful Ping Response:

{"object":true,"errors":null}

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
  • Contact the API token issuer to check that the token is still valid

API Definitions

Our online API definition documentation can be found at https://live.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 support@machship.com

    • Related Articles

    • Machship API Integration Workflow Guide

      The objective of this article is to give you a quick-start guide in working with our API to achieve common integration workflows, and how that affects which API endpoints you wish to use. API Authentication & Documentation Our API accepts and returns ...

    • Common API Error Responses

      MachShip does its best to return meaningful error messages when there is something wrong with the API calls. If there is any error, MachShip will return a response that looks similar to the one below: {      "object":null,    "errors":[         {   ...

    • Cin7 API Key Generation & Access

      Please follow these steps to generate a Cin7 API Key: Go to the Cin7 website and login to your Cin7 account Click the Gear for Settings in the bottom left. Select Integrations and click API v1 Copy/paste the API Username into an email to us, then ...

    • RESTful API Integration and Set up

      RESTful API The restful API is a layer of a programming architecture that exposes a fixed, documented set of GET and POST methods that can be used to integrate advanced backend customer systems with MachShip. This layer of integration is the most ...

    • How to Edit Consignments Via The API

      The following article will cover how to edit a consignment via the API. The main use cases for an edit workflow include: Adjusting item weights/dimensions Adding new items Removing items Note: This article will not cover the basics of creating ...