API Documentation
Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019
Getting Started
TradeLens uses Swagger for its APIs. Swagger is a common framework for documenting REST APIs. Before starting your work with TradeLens, you should familiarize yourself with Swagger (if necessary), at https://swagger.io.
There are 4 sets of APIs: Event Publish, Subscription, Query, and Document Sharing. The steps below will help you understand how to work with Swagger and the APIs.
-
Become familiar with the REST APIs: Start reviewing the documentation by expanding the API definitions in Swagger. You can read the specification and submit test events from the APIs in the Sandbox environment. This will help you understand the APIs prior to writing any code. You can find the different API specifications for the platform by selecting them from the top right area Select a spec.
-
Authenticate in Swagger: Authentication is required for Swagger to use the APIs. If you are not already logged in, click on Login, at the top of the API page in the Swagger, and log in with your TradeLens credentials (ID and password). If you have not been provisioned to TradeLens yet, or if you receive a message that you are not a registered user, contact your TradeLens onboarding lead.
-
Test in Swagger: To test an API in Swagger, click on Try it out, modify the sample event body with your test data, and click on Execute to run the API. Check the response code and response body that is returned.
-
Develop client code for calling the APIs: Once you become familiar with the Swagger REST API specification, you can write your client code using any language. Note that publishing events directly from your client code requires using your system ID and the JSON Web Token (JWT) or "bearer" token. Three headers are required on the HTTPS request: Accept, Content-Type, and Authorization. See the Authentication and Token Generation for API usage section for more details.
Swagger URLs
There is Swagger for the Sandbox and Production zones.
Notes:
- If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in the URLs below.
- Before downloading and opening shared documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.
Sandbox Swagger: https://platform-sandbox.tradelens.com/documentation/swagger/ Production Swagger: https://platform.tradelens.com/documentation/swagger/
API Updates
API Release Notes
09/05/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v1/consignments | Query |
New optional request parameter "createdBy" to filter the search to only include consignments created by the named organization. Similarly, a new response value "createdBy" will be included for each matching consignment. |
| GET /api/v1/partners | Business Partners |
List the business partners and requests for the current organization. |
| POST /api/v1/partners | Business Partners |
Send business partner requests to a list of organizations. |
| PATCH /api/v1/partners | Business Partners |
Change the status of multiple business partner requests. |
| GET /api/v1/profile/organization | Business Partners |
Returns the organization's Business Partner profile. |
| PATCH /api/v1/profile/organization | Business Partners |
Updates the organization's Business Partner profile. |
| GET /api/v1/organizations | Business Partners |
List all searchable organizations in the TradeLens Platform. |
08/07/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v2/documents/{id}/metadata | Document Sharing |
The API response formerly had optional fields "originatorId" and "originatorName" at the top level of the JSON. They have been moved to the "actor" section in the array of "documentActions" to represent the origin actor of that action. |
| GET /api/v1/documents/{id}/metadata | Document Sharing |
The API response "actor" section in the array of "documentActions" now has the "originatorId" and "originatorName" to represent the origin actor of that action. |
| GET /api/v1/documents/{id}/content | Document Sharing |
A new "document-hash" header is returned in the response, containing the hash of thee document that is stored on the blockchain. |
| GET /api/v1/transportEquipment/transportSummaries/{id} | Query |
New values added to the "eventFilter". Formerly "all" and "latest" were the options. Now "plannedAll" and "plannedLatest" have been added to limit the events returned to only planned events. |
07/11/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v1/consignments/consignmentId | Query |
This API has been deprecated for at least one month, so it will now be hidden. In another month, the plan is to remove support entirely. The replacement API is GET /api/v1/tradeObjectIds. |
| GET /api/v1/transportEquipment/transportEquipmentId | Query |
This API has been deprecated for at least one month, so it will now be hidden. In another month, the plan is to remove support entirely. The replacement API is GET /api/v1/tradeObjectIds. |
| GET /api/v1/consignments | Query |
New request parameter "status" that can currently have the value of "Active" or "Canceled" and enables the returned list of consignments to be filtered based on the given state. Similarly, "status" is also a new response attribute for each consignment returned. |
| GET /api/v1/consignments/transportSummaries/{id} | Query |
New response attribute "status" for each consignment, representing its current state ("Active" or "Canceled"). |
| POST /api/v1/tradeObjectIds | Query |
New optional response attribute "relatedTradeObjectIds", an array of additional unique trade object identifiers. |
| PUT /api/v1/actionableDocFlows/shippingInstruction | Actionable Flows |
(Beta) The response attribute, "carrierOrgId" was removed. |
| PUT /api/v1/actionableDocFlows/verifyCopy | Actionable Flows |
(Beta) Triggers the actionable flow associated with the Verify Copy structured document. |
| GET /api/v1/flowTransactions | Actionable Flows |
(Beta) New response attribute "txnStartTime" representing the time when the transaction was created, for each transaction returned in the array. |
| GET /api/v1/flowTransactions/{id} | Actionable Flows |
(Beta) New response attribute "txnStartTime" representing the time when the transaction was created. |
07/02/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| PUT /api/v2/documents | Document Sharing |
New optional request fields to represent the originator so that one network member can upload documents on behalf of another. This is similar to the event publishing APIs. "originatorId" - id of the originator of a document "originatorName" - name of originator of a document |
| GET /api/v2/documents/{id}/metadata | Document Sharing |
New optional response fields to represent the originator of a document given that it may have been uploaded by a different network member. "originatorId" - id of the originator of a document "originatorName" - name of originator of a document |
| POST /api/v1/subscriptions/country POST /api/v1/subscriptions/port POST /api/v1/subscriptions/org |
Subscription |
New optional request array field "docEventFilters" enabling a subscription filtered on document events to be further filtered by the represented document type and action taken on that document. |
| GET /api/v1/consignments GET /api/v2/consignments/{id} |
Subscription |
New optional response array field "docEventFilters" representing a filtered subscription based on document types and actions. |
06/13/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/subscriptions/org | Subscription |
New request and response field "orgEventTypes", an array of strings representing the filtered set of events types that should be sent to the given subscription, similar to port and country subscriptions. |
| GET /api/v1/subscriptions/{id} | Subscription |
New response field "orgEventTypes", returned only for org type subscriptions, an array of strings representing the filtered set of events types that should be sent to the given subscription, similar to port and country subscriptions. |
| Several old APIs with path /visibility/v1/* | Event Publish, Query, and Subscription |
These APIs were deprecated for a while, and then hidden from Swagger for months after. After verifying they are no longer being used, the APIs have been removed. |
05/30/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v2/consignments | Event Publish |
The "equipmentType" field in the request is now optional rather than mandatory. It can be found in the "transportEquipmentDetails" of the "bookingData". |
| GET /api/v1/consignments | Query |
New "callerRoles" field in the response body. It is an array of strings representing the roles of the API caller in the resulting consignments. |
| GET /api/v1/consignments/transportSummaries/{id} | Query |
New "callerRoles" field in the response body. It is an array of strings representing the roles of the API caller in the resulting consignment. |
| GET /api/v1/transportEquipment/transportSummaries/{id} | Query |
New "callerRoles" field in the response body. It is an array of strings representing the roles of the API caller in the resulting transport equipment. |
05/20/2019
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/consignments/consignmentSubcontracted | Event Publish |
To support consignment hierarchies, this allows a relationship to be established between a consignment and its subconsignment. |
| POST /api/v1/consignments/transportEquipmentAdded | Event Publish |
The POST /api/v2/transportEquipment API should be used instead. The carrier booking number is a required field and establishes the linkage between the consignment and transport equipment. |
| GET /api/v1/consignments | Query |
New response fields have been added to the consignments array. "cutOffs" - cutoff deadline dates for all the transport equipment in this consignment. "bookingData" - data from the latest POST /api/v1/consignments. "parentConsignmentId" - reference to a parent consignment when part of a consignment hierarchy. "subcontractIds" - reference to subconsignment IDs when part of a consignment hierarchy. |
| GET /api/v1/consignments/events/{id} | Query |
New response field "description" is returned as part of the location of an event. |
| GET /api/v1/transportEquipment/events/{id} | Query |
New response field "description" is returned as part of the location of an event. |
| GET /api/v1/consignments/transportSummaries/{id} | Query |
New response field "description" is returned as part of several location objects. |
| GET /api/v1/transportEquipment/transportSummaries/{id} | Query |
New response field "description" is returned as part of several location objects. |
| PUT /api/v1/actionableDocFlows/billOfLading | Actionable Flows |
Parse a Bill of Lading JSON document and handle the associated creation and setup of consignments and transport equipment. |
| PUT /api/v1/actionableDocFlows/shippingInstruction | Actionable Flows |
Parse a Shipping Instructions JSON document and handle the associated creation and setup of consignments and transport equipment. |
| GET /api/v1/flowTransactions | Actionable Flows |
Fetch all actionable flow transactions. |
| GET /api/v1/flowTransactions/{id} | Actionable Flows |
Fetch a specific actionable flow transaction. |
| GET /api/v1/documentSchema | Document Sharing |
Deprecated in favor of the new V2 version of the API. |
| GET /api/v2/documentSchema | Document Sharing |
Replaces the deprecated V1 version of the API, providing more flexibility to handle documents associated with both consignments or transport equipment. |
| GET /api/v1/documents/{id}/metadata | Document Sharing |
Deprecated in favor of the new V2 version of the API. |
| GET /api/v2/documents/{id}/metadata | Document Sharing |
Replaces the deprecated V1 version of the API, providing more flexibility to handle documents associated with both consignments or transport equipment. |
| POST /api/v1/documents/bulk/documents | Document Sharing |
Deprecated in favor of the new V2 version of the API. |
| POST /api/v2/documents/bulk/documents | Document Sharing |
Replaces the deprecated V1 version of the API, providing more flexibility to handle documents associated with both consignments or transport equipment. |
| POST /api/v1/documents/search | Document Sharing |
Deprecated in favor of the new V2 version of the API. |
| POST /api/v2/documents/search | Document Sharing |
Replaces the deprecated V1 version of the API, providing more flexibility to handle documents associated with both consignments or transport equipment. |
| PUT /api/v1/documents | Document Sharing |
Deprecated in favor of the new V2 version of the API. |
| PUT /api/v2/documents | Document Sharing |
Replaces the deprecated V1 version of the API, providing more flexibility to handle documents associated with both consignments or transport equipment. |
05/08/2019
| API Description | Change | Notes |
|---|---|---|
| PATCH /api/v1/documentSchema/{id} | New | Deprecates a given version of a Document Schema |
| GET /api/v1/documentSchema | Deprecated | Replaced by the new /api/v2/documentSchema API that allows a more organized response to show active and inactive versions of the same schema. However, to aid the transition, a couple of changes were applied. A new optional request parameter, "includeInactive", allows the filtering of active vs inactive Document Schemas. Related, a new "status" field is included in the response. |
| GET /api/v2/documentSchema | New | This new version of the API supports multiple versions (active and inactive/deprecated) of the same schema whereas the former API only delivered the latest, active version. The response payload is more organized. |
| GET /api/v1/documentSchema/{id} | Changed | New optional request parameter, "includeInactive". Set to true to fetch nonactive Document Schema. Related, a new "status" field is included in the response. |
| POST /api/v1/tradeObjectIds | New | Query for a TradeLens object id by external references. Note, this is a "POST" because the search criteria is a complex JSON object that cannot be reduced to a fixed set of key/value pairs (typically used as a list of query parameters in a "GET"). |
| GET /api/v1/transportEquipment/transportEquipmentId | Deprecated | Replaced by the new generic API to search for trade object IDs. |
| GET /api/v1/consignments/consignmentId | Deprecated | Replaced by the new generic API to search for trade object IDs. |
| GET /api/v1/consignments/events/{id} | Changed | New fields in the response, as part of the events array, to support newly named fields in document events. The fields are "action" and "doc". The "doc" field is a JSON object with several fields. In addition, a new field called "senderOrgName" is part of the events array to indicate the name of the organization that sent the event. |
| GET /api/v1/transportEquipment/events/{id} | Changed | Same as above, in GET /api/v1/consignments/events/{id} |
| GET /api/v1/consignments/transportSummaries/{id} | Changed | A new field called "senderOrgName" is part of the events array to indicate the name of the organization that sent the event. |
| GET /api/v1/transportEquipment/transportSummaries/{id} | Changed | A new field called "senderOrgName" is part of the events array to indicate the name of the organization that sent the event. |
| GET /api/v1/transportEquipment/partyAdded | New | Add visibility to documents associated with a piece of transport equipment. The feature to associate documents with a piece of transport equipment is coming soon. Note, this API is different from adding a party to a consignment which grants visibility to both events and documents. Once a party has been granted visibility to a consignment, that party is already automatically granted access to events of associated transport equipment. |
04/11/2019
| API Description | Change | Notes |
|---|---|---|
| GET /api/v1/documents/{id}/metadata | Changed | Additional fields: "docReferences" and "identifiers" in the document object. |
| PUT /api/v1/documents | Changed | Additional fields: "docReferences" and "identifiers" in the document object. |
04/04/2019
(last updated on 4/11/2019)
| API Description | Change | Notes |
|---|---|---|
| POST /api/v1/consignments | Deprecated | Being replaced with v2 POST. See below. |
| POST /api/v2/consignments | New | Creates or updates a consignment. Does not return the consignment or delegation IDs, but they can be fetched with the new query endpoints described below. |
| GET /api/v1/consignments/delegationIds | New | Query the delegation IDs for a consignment given a carrier booking number. |
| GET /api/v1/consignments/consignmentId | New | Query the consignment ID for a consignment given a carrier booking number. |
| GET /api/v1/consignments | Changed | Additional fields for searching: commodity harmonized code and commodity description. Related, the response JSON schema has several new fields related to commodities. |
| GET /api/v1/consignments/events/{id} | New | Query for consignment events given a delegation ID. |
| PATCH /api/v1/consignments/*** | Deprecated | Being replaced to use a POST instead of a PATCH. See below. |
| POST /api/v1/consignments/*** | New | Replaces the former PATCH listed above. |
| POST /api/v1/transportEquipment | Deprecated | Being replaced with v2 POST. See below. |
| POST /api/v2/transportEquipment | New | Creates or updates a transport equipment. Does not return the transport equipment ID or delegation IDs, but they can be fetched with the new query endpoint described below. |
| GET /api/v1/transportEquipment/delegationIds | New | Query the delegation IDs for a transport equipment given a carrier booking number and equipment number. |
| GET /api/v1/transportEquipment/transportEquipmentId | New | Query the transport equipment ID for a transport equipment given a carrier booking number and equipment number. |
| GET /api/v1/transportEquipment/transportSummaries/{id} | Changed | Additional booking data fields added in the response JSON schema within the array of related consignments. |
| PATCH /api/v1/transportEquipment/*** | Deprecated | Being replaced to use a POST instead of a PATCH. See below. |
| POST /api/v1/transportEquipment/*** | New | Replaces the former PATCH listed above, except for "locationsUpdated" that has function replaced by dynamic transport plan functionality. |
| POST /api/v1/documentEvents/*** | Changed | No longer deprecated. |
| PATCH /api/v1/documentSchema/{id} | New | Similar to the v1 version, but adds support for new docReferences and identifiers fields. |
| GET /api/v1/documentSchema | Changed | New request parameter to include inactive schemas and a new response attribute to indicate the status of the schema. |
| GET /api/v1/documentSchema/{id} | Changed | New request parameter to include inactive schemas and a new response attribute to indicate the status of the schema. |
| GET /api/v1/documents/{id}/metadata | Changed | New response attributes: docReferences, identifiers. |
| PUT /api/v1/documents | Changed | New response attribute: docReferences, identifiers. |
03/14/2019
| API Description | Change | Notes |
|---|---|---|
| GET /api/v1/consignment/delegationIds | New | Query the delegation IDs for the consignment related to a given carrier booking number. |
| GET /api/v1/consignment/consignmentId | New | Query the consignment ID for the consignment related to a given carrier booking number. |
| GET /api/v1/transportEquipment/delegationIds | New | Query the delegation IDs for the transport equipment related to a given carrier booking number and equipment number. |
| GET /api/v1/transportEquipment/transportEquipmentId | New | Query the transport equipment ID for the transport equipment related to a given carrier booking number and equipment number. |
| POST/GET /visibility/v2/subscriptions/* | Hidden | Formerly deprecated subscription APIs have been removed from Swagger, but will continue to function for one more month before being disabled completely. |
| POST /api/v1/transportEquipment | Updated | A new equipmentType: 45R0: "REEFER HIGHCUBE (MECHANICALLY REFRIGERATED)" was added to the current list of equipment types. |
| PATCH /api/v1/transportEquipment/equipmentNumberUpdated | Updated | A new equipmentType: 45R0: "REEFER HIGHCUBE (MECHANICALLY REFRIGERATED)" was added to the current list of equipment types. |
02/28/2019
| API Description | Change | Notes |
|---|---|---|
| GET /api/v1/documents/* | Update | The "fileType" field was added in the response for all document sharing APIs except the bulk download. |
| POST /api/v1/transportEquipment/equipmentNumberUpdated | Update | The optional field "equipmentType" was added to the request schema. When present, the UI and query APIs will reflect the newly assigned value. |
| Event schema JSON for published events that related to documents. | Update | The "platformDocumentVersion" field was added to the document events published to subscriptions. |
| POST /visibility/v1/events/E*** (Multiple events removed - see Notes) | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. These events are all the old E*** events that are NOT associated with a document based event. The only remaining deprecated events in the Event Publish API swagger are associated with documents. |
| POST /visibility/v2/events/E468 | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
| GET /visibility/v1/shipments | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
| GET /visibility/v1/countryCodes | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
| GET /visibility/v1/eventTypes | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
| GET /visibility/v1/transportSummaries/{delegationId} | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
| GET /visibility/v1/events/{delegationId} | Hidden | Removed from Swagger after being deprecated. Will work for 1 more month. |
API Refactoring Reference
If you were using the TradeLens APIs prior to early December 2018, the APIs have been refactored and the endpoints have changed. The information below can help you map the old APIs to the new APIs so you can make any necessary changes to your programs.
You can zoom and scroll to see the full content in the window below. There is also a download link at the bottom of the page for the PDF.
Note: Before downloading and opening documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.
Download the TradeLens_API_Refactoring_mapping.pdf document.