Getting Started with Ship's APIs

  • Ship
  • api
  • getting started

Welcome to Ship! This page contains a brief overview of Ship's APIs and explains how you can use them.

API Collection Overview

Ship's Shipments functionality was introduced in version 2 as an extension to the Ship (Consignments) API suite used in version 1. Ship's Shipments API collection offers unparalleled flexibility, with support for on-demand collections from multiple locations (e.g. a ship-from-store model) as well the regular scheduled fulfillment centre collections supported in v1.

Ship also offers the ability to group shipments together for ease of management, an improved dangerous goods specification and enhanced customs functionality, among many other features.

Ship's APIs enable you to:

  • Manage Shipments - Create, update, clone and cancel shipment records, and manually modify shipment states.
  • Allocate Shipments - Allocate shipments to the most appropriate carrier service.
  • Manage Quotes - Create and receive delivery quotes for shipments.
  • Get Customs Docs - Get customs documents for allocated international shipments.
  • Get Labels - Get delivery labels for an allocated shipment in either ZPL or PDF format.
  • Manifest Shipments - Manually manifest one or more either individually or by manifesting a shipment group.
  • Manage Shipment Groups - Group shipments together so they can be operated on as a single unit, and edit or delete shipment groups as required.
  • Get Collection Notes - Retrieve collection notes (aka driver's manifest) by search query or by shipment group.
Note

For example API call flows and reference information, see the Ship API reference.

Making an API Request in Ship

This section explains the various API headers used when making a request to one of Ship's APIs.

x-api-key: [qwerrtyuiioop0987654321]
Accept: application/json
Content-Type: application/json 
Accept-Encoding: gzip 
x-api-version: 1.1

Authentication

You must provide a valid API key in every call you make to Ship. When a new user account is created, Ship generates a unique API key and allocates it to the new user. You can view your API key in the Ship's user interface.

Note

Ship admins can manage users in the UI. For information on configuring Ship user accounts and permissions, see the Managing Users and Roles page of the Ship Admin User Guide.

To use your API key with Ship, include it in an x-api-key header when making calls. If you make an API call to Ship without including an API key, then Ship returns an error with a status code of 401 (Unauthorized).

Formats

Ship only works with JSON data. This is a change from v1, which accepted XML requests and responses as well as JSON.

If you provide an Accept header to indicate request format and/or a Content-Type format to indicate response format, then these keys must have a value of application/json. Ship will return an error if you provide any other values in these headers. If you do not provide Accept and/or Content-Type headers, then Ship uses its default value of application/json.

Ship is designed to work with GZIP encoding. We strongly recommend that you provide an Accept-Encoding header with a value of gzip in all requests.

Versioning

You must provide an x-api-version header in all requests. The current API version is 1.1.

Note

The API version provided in the x-api-version header is a purely technical property, and should not be confused with the version of Ship you are using. At present, the x-api-version should always 1.1, irrespective of whether you are calling Ship or Ship (Consignments) endpoints. This is because both versions of Ship share certain back-end processes.

Response Headers

Depending on the content returned, Ship's responses may include the following headers:

  • x-api-version - The version of the API that served the request.
  • Content-Type - The format of the response body. This will ordinarily have the value application/json.
  • Content-Encoding - If you request responses in GZIP format, the Content-Encoding response header returns a value of gzipped.

Using the Sandbox Environment

All of the URLs and examples given in this documentation relate to Ship's live production environment. However, Ship also offers a sandbox, enabling you to use a "safe" development environment in which you can integrate with Ship without running the risk of inadvertently transmitting data to carriers. The sandbox works in exactly the same way as the production environment, but is entirely self-contained and uses a separate dataset.

In order to call APIs in the sandbox environment, you will first need to set up a sandbox API key. To call an API in the sandbox rather than the production environment, substitute the api.sorted.com/pro portion of the API's base URL with api.sorted.com/pro-sandbox and make sure to use your sandbox API key (as opposed to your production API key) in the x-api-key header when making the call.

For example, to call the Create Shipment endpoint in the production environment, you would send a POST request to https://api.sorted.com/pro/shipments. To call the same endpoint in the sandbox, you would send a POST request to https://api.sorted.com/pro-sandbox/shipments.

Next Steps