Overview

The ISO API enables you to programmatically interact with ISO’s supply chain data.

The API follows modern RESTful API conventions and uses JSON (JavaScript Object Notation) as the data interchange format. For authentication, it uses HTTP Basic Authentication.

ℹ️ NOTES:

All contacts are optional
Timestamps should support any properly-formatted ISO8601 datetime. This could be UTC or another, specified offset. It will be converted and stored as UTC in the ISO database.
- e.g. “2023-06-12T12:36:47-05:00” is valid and would be stored in the database (and returned in subsequent API calls) as “2023-06-12T17:36:47.589Z”
Dates, where applicable, should be ISO8601-formatted, as YYYY-MM-DD.

Endpoint Parameters and Responses

By default, the API documentation displays request parameters and sample response data for each endpoint once you click on its URL path.

Field Descriptions

For field descriptions, data types, and expected formats, please see the “Schema” section of each endpoint. Full schemas are also available at the bottom of the API doc.

Working with the API

First, POST entities that will be reused across many shipments (Carriers, Facilities, Shippers, etc). Then, begin POSTing Shipment records. See the following flow diagram for an overview.

Data Model

The below data model shows how the various broker entities are involved in the shipments creation

Shipments

What is a shipment? A shipment in the ISO platform represents a completed shipment, including both the origin (start) and destination (end) stops.

Create your first shipment inside the ISO platform:

Based on the data model above, you will see that in order to create a shipment in ISO, you first need to create the associated:

Carrier
Shipper
Consignee
Origin facility (associated with a shipper or consignee)
Destination facility (associated with a shipper or consignee)

All of these elements are required in the Shipment POST body.

The diagram below outlines the steps of a shipment creation and the overall data load process, including differentiating between the initial data load and ongoing data loads:

Authentication

ISO’s APIs use an API key to authenticate.

ISO currently uses Basic Authentication. During implementation, your ISO Implementation Manager will create a user in both ISO’s broker sandbox and production environments for which API keys will be generated and provided to the user.

The user will then use the ISO user email address as the username, and the appropriate API key as the password for Basic Authentication.

Postman

Postman is a free API platform which can be used to access the ISO API, both for the Ingestion API and the Performance API. A web and desktop application for Postman are available.

Using the Basic Authentication credentials provided by the ISO Implementation Manager, a user can POST or GET to the endpoints provided in the Swagger documentation.

To access the Staging API, use the host https and scheme 4970-broker-sandbox.staging.iso.io

https://4970-broker-sandbox.staging.iso.io

To access the Production API, use the host https and scheme api.iso.io

https://api.iso.io

Complete the query with any of the endpoints provided in the Swagger documentation.

Testing and Populating Data to the ISO App

As mentioned above, you will receive API credentials for both the ISO Staging and Production environments. But where will you test and populate data and when?

Here is the basic outline for testing and populating final data in ISO:

Test all API endpoints in Staging Environment using Staging credentials
1. Iron out questions and errors with each endpoint
2. Successfully POST carriers, shippers, consignees, facilities and shipments to Staging
3. Finalize any internal API processes
Send all data to Production using Production credentials (12 month seed or data moving forward)
Validate data in Production (including validation by ISO team)
ISO team will coordinate training in Production once data is populated

Broker KPI Shipment Field Prioritization

The Shipments endpoint is the most complex of the mapping requirements, pulling in many fields and incorporating many pieces of data (bookings, financials, etc). Therefore, you can use the Broker KPI Shipment Field Prioritization document to help inform which fields to prioritize mapping and posting based on which are required, inform KPIs, or inform other system functionality such as filtering.