The Shipsi API uses API keys to authenticate requests. You can view your API key in your account settings within your self-serve portal.

Your API keys have the full Shipsi capabilities so make sure you keep it secure! Do not share your API key in public areas such as GitHub, client-side code, or other compromising locations.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

There are a lot of ways you can make an HTTPS request to the Shipsi API. A request can be raw over HTTPS in your code (such as using a module in NodeJS) or API tools like Postman.

All requests to Shipsi's REST API need to be authenticated. Shipsi supports authenticating using HTTPS basic auth, which use the an API key that uniquely identifies a user as authorized.

Shipsi uses API keys to authenticate API requests. You can view your API key in your self-serve portal.

API requests without authentication will fail.

Shipsi uses POST, PUT, and GET HTTPS method on differing resources. Here's how those method is used for Shipsi's most common resource: Create Delivery resource.

You can create a resource using the HTTP POST method on a resource URI. You can view the parameters for any post request in the documentation for a resource. Here's a POST request which will create and send a delivery driver via the Shipsi API.

You’ve scheduled the delivery! You can see in the output a platform_reference_id. You can use that platform_reference_id to edit the delivery information prior to dispatch.

While you can get event alerts via webhook there may be times you want to check the status of a delivery directly. You can use the same platform_order_id to make an HTTPS GET request to the List Deliveries resource.

Shipsi uses conventional HTTP response codes to indicate the success or failure of an API request. Generally it can be known: Codes within the 2xx range mean success. Codes within the 4xx range mean failure due to the information given (such as, a required parameter was omitted, an address was invalid, the scheduled time is in the past.). Codes within the 5xx range mean their is an error on our end.

Because many 4xx errors can be handled programmatically we do our best to provide a code which explains the reported error.

JSON

Shipsi returns resource representations as JSON.

Exceptions

Shipsi returns exceptions in the HTTPS response body when something goes wrong. An exception has up to four properties:

Examples

Example 1

Here is a simple 404:

Example 2

An invalid POST to the Create Delivery resource without a 'Address_1' parameter would return:

Some objects allow the request for more information shown as an expanded response using the expand request parameter. On all API requests this parameter is available, but only applies to that request alone. Responses can be expanded once or multiple times in nested fashion.

To expand a response you must use the applicable related object ID within the response properties given. A good example of this is the Compare Rates API request will return quote IDs. Those quote ID objects can be expanded inline with the expand request parameter. Within this documentation we note objects which can be expanded with the expand request parameter.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting location_id.location_package on shipping rate will expand the location_id property into a full Location object, and will then expand the location_package property on that location into a full Package object.

This parameter can be used on any endpoint that returns expandable fields. Using multiple deep expansions on requests can be slow.

Expansions have a maximum depth of three levels.

The Shipsi API supports built in idempotency. Many requests can be retried with the same parameters repeatedly and not cause any negative result.

Requests to endpoints which action events that carry a cost or associated live event are idempotent by default. All of these requests must be unique or will fail.

Request results only save if an endpoint starts executing. If request parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. These requests can always be retried.

When changes are made to the API which are not compatible with previous versions Shipsi releases a new dated API. changes are made to the API, a new, dated version is released. The current version is 2020-10-01.

Check our changelog to keep up to date on any of these changes to our API.

Shipsi’s REST API for HTTPS requests from your application to Shipsi works well for purposes such as quoting a delivery cost or dispatching a driver, but what happens when we receive data which you also may need? When Shipsi processes data which is resulting from the outcomes of your requests you can get this data too. An example of this would be after you created a delivery a driver is dispatched. You need to know when this driver has reached certain points to trigger or plan actions on your side - you can get this data via webhooks.

As certain events occur, Shipsi has access to this data in real time - these events are different for each Shipsi product. We can send these to you via HTTPS requests. These requests are called webhooks. Generally, your application would get an HTTP callback because the event is useful or should probably be handled by your application.

A perfect example is after a customer gets a package delivered you may want to send them a survey to understand their experience. This can easily be handled if you have data on when the package was delivered. A webhook can be sent to your application which alerts you of that event. Now you can have a function which detects the completed delivery alert and sends an email survey accordingly.

The majority of the time webhooks are used when your systems don’t maintain an open connection to Shipsi - so Shipsi makes an independent HTTPS request to your server.

Shipsi webhooks are informational. No response from your application is required, aside from a standard HTTP status code of 200 (OK).

You can set your webhook URL via the self-serve portal to be notified about events that happen in real time for various resources

Now that you understand what rules and architecture apply to all of Shipsi’s products you can dive right in and find a solution which fits your needs!