API Documentation

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2020

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 several sets of APIs (some are available based on your organization's role): Event Publish, Subscription, Trade Object, Document Sharing, Actionable Flows, Business Partners, Platform Constants, etc. 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 definition.

  • 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

03/19/2020

API Description Change / Swagger API Notes
POST /api/v1/genericEvents/customsHold New /
Event Publish
New event to recognize an authority or terminal has communicated that the transport equipment must not be loaded.
POST /api/v1/genericEvents/vgmReceived New /
Event Publish
New event to recognize that the verified gross mass (VGM) has been received.
POST (several) Changed /
Event Publish,
Event Subscription,
Trade Object
Several APIs now clearly document the potential for a error response code of HTTP 429 to represent that too many requests have come from the same sender within the same second, representing rate limiting. Changes were only made to properly document this in Swagger. The behavior has been there for a long time.
GET​ /api​/v1​/roles New /
Platform Constants
Returns list of supported roles in TradeLens.
GET​ /api​/v1​/documentTypes New /
Platform Constants
Returns list of supported document types in TradeLens.
GET​ /api​/v1​/documentActions New /
Platform Constants
Returns list of supported document actions in TradeLens.

03/05/2020

API Description Change / Swagger API Notes
POST /api/v1/actionableFlows New /
Actionable Flows
Query all actionable flows based document type and trade object identifiers.
POST /api/v1/actionableFlows/search Changed /
Actionable Flows
New request parameter, "flowState", has been added to filter searching based on an actionable flow being in the issued, transferred, or surrendered state.
POST /api/v1/subscriptions/webhook/performTest New /
Event Subscription
Publish a test event to a webhook.
POST /api/v1/subscriptions/{id}/disable New /
Event Subscription
Manually disable the given subscription.
POST /api/v1/subscriptions/{id}/enable New /
Event Subscription
Manually enable the given subscription.
POST /api/v1/subscriptions/{id}/status New /
Event Subscription
Return the status of a given subscription (enabled or disabled).

02/25/2020

API Description Change / Swagger API Notes
POST /api/v1/actionableFlows/search Changed /
Actionable Flows
New request parameters and response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
POST /api/v1/actionableMessageFlows/
docMessages
Changed /
Actionable Flows
New request parameters and response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
POST /api/v1/flowTransactions Changed /
Actionable Flows
New request parameters and response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
GET /api/v1/flowTransactions/{id} Changed /
Actionable Flows
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
PUT /api/v1/actionableDocFlows/
billOfLading
Changed /
Actionable Flows
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
PUT /api/v1/actionableDocFlows/
shippingInstruction
Changed /
Actionable Flows
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
PUT /api/v1/actionableDocFlows/
verifyCopy
Changed /
Actionable Flows
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId".
POST /api/v1/shipments New /
Event Publish
As part of the new shipments feature, this event represents the creation of a shipment.
POST /api/v1/shipments/
consignmentAdded
New /
Event Publish
As part of the new shipments feature, this event associates a shipment with a consignment.
POST /api/v1/shipments/
partyAdded
New /
Event Publish
As part of the new shipments feature, this event grants visibility of a party to a shipment.
POST /api/v1/shipments/
partyListUpdated
New /
Event Publish
As part of the new shipments feature, this event updates the list of parties who have access to a shipment.
POST /api/v1/shipments/
partyRemoved
New /
Event Publish
As part of the new shipments feature, this event removes visibility of a party to a shipment.
POST /api/v1/shipments/
referenceAdded
New /
Event Publish
As part of the new shipments feature, this event adds a reference to a shipment, which can later be used for search.
POST /api/v1/shipments/
referenceListUpdated
New /
Event Publish
As part of the new shipments feature, this event updates the list of references to a shipment for the given caller.
POST /api/v1/shipments/
referenceRemoved
New /
Event Publish
As part of the new shipments feature, this event removes a reference from a shipment.
POST /api/v1/consignments/
partyListUpdated
Changed /
Event Publish
New optional request parameter "issuanceTime8601" can now be provided as an ISO 8601 formatted timestamp used by the platform to determine the most recent party list update.
POST /api/v1/consignments/
referenceListUpdated
Changed /
Event Publish
New optional request parameter "issuanceTime8601" can now be provided as an ISO 8601 formatted timestamp used by the platform to determine the most recent reference list update.
POST /api/v1/transportEquipment/
partyListUpdated
Changed /
Event Publish
New optional request parameter "issuanceTime8601" can now be provided as an ISO 8601 formatted timestamp used by the platform to determine the most recent party list update.
POST /api/v1/transportEquipment/
referenceListUpdated
Changed /
Event Publish
New optional request parameter "issuanceTime8601" can now be provided as an ISO 8601 formatted timestamp used by the platform to determine the most recent reference list update.
POST /api/v2/subscriptions/
delegationId
Changed /
Subscription
This formerly deprecated API is being hidden from the Swagger API documentation, with plans to disable it after a month.
GET /api/v1/shipments New /
Trade Object
Search for shipments based on various matching fields.
GET /api/v1/shipments/creators New /
Trade Object
Query for the names of all organizations that have created a shipment for which the user has access.
GET /api/v1/shipments/{id}/events New /
Trade Object
Fetch all the events for a given shipment.
POST /api/v1/tradeObjectIds Changed /
Trade Object
Support has been added to search for shipments based on references. The response will have a "shipmentId" pointing to a matching shipment if found.
GET /api/v1/transportEquipment/
splitFromConsignment/{id}
Changed /
Trade Object
Consignments in the response will now include the "billOfLadingNumber" if applicable.
GET /api/v1/transportEquipment/
transportSummaries/consignmentId/{id}
Changed /
Trade Object
Consignments in the response will now include the "billOfLadingNumber" if applicable.
GET /api/v1/transportEquipment/
transportSummaries/splitFromConsignment/{id}
Changed /
Trade Object
Consignments in the response will now include the "billOfLadingNumber" if applicable.
GET /api/v1/transportEquipment/
transportSummaries/transportEquipmentId/{id}
Changed /
Trade Object
Consignments in the response will now include the "billOfLadingNumber" if applicable.
GET /api/v1/transportEquipment/
transportSummaries/{id}
Changed /
Trade Object
Consignments in the response will now include the "billOfLadingNumber" if applicable.

02/10/2020

API Description Change / Swagger API Notes
GET /api/v1/referenceTypes New /
Platform Constants
Retrieves all reference types used in the platform (associated with trade objects), with their code, type and description.
POST /api/v1/actionableFlows/search New /
Actionable Flows
New API to fetch actionable flows based on the flow type and trade object identifier.
POST​ /api​/v1​/actionableMessageFlows​/docMessages Changed /
Actionable Flows
Several changes/cleanup for this Beta API including the introduction of required field "actionIdentifiers" describing the action being taken. The "documentAction" field has been removed and the "documentHash" field has been moved to the relevant actionIdentifers.
GET /api/v2/consignments New /
Query
This new v2 version of the API changes the response payload to include a new list of "references" (including both a type and a value), no longer including the former "consignmentRefs" array found in the older v1 endpoint. 
POST /api/v1/tradeObjectIds Changed /
Query
The following changes have been made to the request parameters in support of searching for trade objects based on references:
- consignment/references[]/type is no longer required
- new: transportEquipment/references[]/reference
- new: transportEquipment/references[]/type
GET /api/v1/consignments/events/
consignmentId/{}
Changed /
Query
The following new attribute has been added to indicate the target organization of an actionable flow transaction:
- events[]/destinationOrgName (in: body, type: string)

The following new attributes have been added to the response schema as part of supporting arrays of seals:
- events[]/seals[]/sealNumber
- events[]/seals[]/sealType 
GET /api/v1/consignments/events/{} Changed /
Query
The following new attribute has been added to indicate the target organization of an actionable flow transaction:
- events[]/destinationOrgName (in: body, type: string)

The following new attributes have been added to the response schema as part of supporting arrays of seals:
- events[]/seals[]/sealNumber
- events[]/seals[]/sealType 
GET /api/v1/transportEquipment/
events/consignmentId/{}
Changed /
Query
The following new attribute has been added to indicate the target organization of an actionable flow transaction:
- events[]/destinationOrgName (in: body, type: string)

The following new attributes have been added to the response schema as part of supporting arrays of seals:
- events[]/seals[]/sealNumber
- events[]/seals[]/sealType
GET /api/v1/transportEquipment/
events/transportEquipmentId/{}
Changed /
Query
The following new attribute has been added to indicate the target organization of an actionable flow transaction:
- events[]/destinationOrgName (in: body, type: string)

The following new attributes have been added to the response schema as part of supporting arrays of seals:
- events[]/seals[]/sealNumber
- events[]/seals[]/sealType
GET /api/v1/transportEquipment/
events/{}
Changed /
Query
The following new attribute has been added to indicate the target organization of an actionable flow transaction:
- events[]/destinationOrgName (in: body, type: string)

The following new attributes have been added to the response schema as part of supporting arrays of seals:
- events[]/seals[]/sealNumber
- events[]/seals[]/sealType 
POST /api/v1/consignments/
referenceListUpdated
New /
Event Publish
Enables the full list of consignment references added by the caller to be updated in a single event.
POST /api/v1/consignments/
referenceRemoved
New /
Event Publish
Enables the removal of consignment. references formerly added by the caller.
POST /api/v1/transportEquipment/
referenceListUpdated
New /
Event Publish
Enables the full list of transport equipment references added by the caller to be updated in a single event.
POST /api/v1/transportEquipment/
referenceRemoved
New /
Event Publish
Enables the removal of transport equipment references formerly added by the caller.
POST /api/v2/consignments/referenceAdded New /
Event Publish
This new version 2 of the API enables a list of consignment references to be added at one time, along with related metadata.
POST /api/v2/genericEvents/
packedContainerSealInspected
New /
Event Publish
This new version 2 of the API enables arrays of seals to be provided rather than just one.
POST /api/v2/genericEvents/
packedContainerSealed
New /
Event Publish
This new version 2 of the API enables arrays of seals to be provided rather than just one.
POST /api/v2/genericEvents/
sealRemoved
New /
Event Publish
This new version 2 of the API enables arrays of seals to be provided rather than just one.
POST /api/v2/transportEquipment/
referenceAdded
New /
Event Publish
This new version 2 of the API enables a list of transport equipment references to be added at one time, along with related metadata.

01/29/2020

API Description Change / Swagger API Notes
GET /api/v1/transportEquipment/
splitFromConsignment/{delegationId}
Deprecated /
Trade Object
All delegation ID based APIs are being deprecated in favor of similar APIs that leverage the the trade object IDs.
GET /api/v1/transportEquipment/
transportSummaries/splitFromConsignment/{id}
New /
Trade Object
New API to replace the similar endpoint that was deprecated due to its use of delegation IDs. The output is enhanced with details about each associated transport plan.
GET /api/v1/transportEquipment/
transportSummaries/{delegationId}
Deprecated /
Trade Object
All delegation ID based APIs are being deprecated in favor of similar APIs that leverage the the trade object IDs.
GET /api/v1/transportEquipment/
transportSummaries/consignmentId/{id}
New /
Trade Object
New API to replace the similar endpoint that was deprecated due to its use of delegation IDs. This one is based on the consignment ID. The output is enhanced with details about each associated transport plan.
GET /api/v1/transportEquipment/
transportSummaries/transportEquipmentId/{id}
New /
Trade Object
New API to replace the similar endpoint that was deprecated due to its use of delegation IDs. This one is based on the transport equipment Id. The output is enhanced with details about each associated transport plan.
GET /api/v1/consignments/
transportSummaries/{delegationId}
Deprecated /
Trade Object
All delegation ID based APIs are being deprecated in favor of similar APIs that leverage the the trade object IDs.
GET /api/v1/consignments/
transportSummaries/consignmentId/{id}
New /
Trade Object
New API to replace the similar endpoint that was deprecated due to its use of delegation IDs. The output is enhanced with details about each associated transport plan.
POST /api/v1/consignments/
partyAdded
Changed /
Event Publish
Two roles were removed: "TRANSPORT_SERVICE_INTERMEDIARY", "DATA_AGGREGATOR".
POST /api/v1/transportEquipment/
partyAdded
Changed /
Event Publish
Two roles were removed: "TRANSPORT_SERVICE_INTERMEDIARY", "DATA_AGGREGATOR".
POST​ /api​/v1​/transportEquipment​/
partyListUpdated
New /
Event Publish
Update the list of parties with access to a piece of transport equipment. This allows bulk upload of parties vs adding one at a time. The list will be managed per caller, so if multiple parties have added the same third party, they would each have to update the list or remove them to eliminate the visibility.
POST ​/api​/v1​/transportEquipment​/
partyRemoved
New /
Event Publish
Remove access to a piece of transport equipment for a formerly added party. This only affects parties added by the same caller.
POST​ /api​/v1​/consignments​/
partyListUpdated
New /
Event Publish
Update the list of parties with access to a consignment. This allows bulk upload of parties vs adding one at a time. The list will be managed per caller, so if multiple parties have added the same third party, they would each have to update the list or remove them to eliminate the visibility.
POST​  /api​/v1​/consignments​/
partyRemoved
New /
Event Publish
Remove access to a consignment for a formerly added party.  This only affects parties added by the same caller.
POST​ /api​/v1​/genericEvents​/
billOfLadingSurrendered
New /
Event Publish
Note that a bill of lading has been surrendered to the carrier.
GET /api/v1/partners Changed /
Business Partners
New "entitlements" request filter to restrict the response to include business partners with a given entitlement. Currently only "bolVerifier" and "eBOL" are supported.
POST​ /api​/v1​/actionableFlows​/search New /
Actionable Flows
Fetch all actionable flows by flow type. (Sandbox zone 01/29/2020, Production zone 02/10/2020)
POST​ /api​/v1​/actionableMessageFlows​/docMessages Changed /
Actionable Flows
Several changes/cleanup for this Beta API including the introduction of required field "actionIdentifiers" describing the action being taken. The "documentAction" field has been removed and the "documentHash" field has been moved to the relevant actionIdentifers. (Sandbox zone 01/29/2020, Production zone 02/10/2020)

12/17/2019

API Description Change / Swagger API Notes
GET​ /api​/v1​/documents​/{documentId}​/printableContent New /
Document Sharing
Fetch a document's printable content, if available.
GET​ /api​/v2​/documents​/{documentId}​/metadata Changed /
Document Sharing
New element of the response within the "documentContentList" called "printableContentMetadata" including information for a potentially associated printable version of the document.

12/05/2019

API Description Change / Swagger API Notes
PUT /api/v1/actionableDocFlows/verifyCopy Changed /
Actionable Flows
New optional request field "printableCopy" used to upload the printable copy for the Verify Copy document. 
PUT /api/v1/actionableDocFlows/billOfLading Changed /
Actionable Flows
New optional request field "printableCopy" used to upload the printable copy for the Bill of Lading document. 
GET​/api​/v1​/transportEquipment​/events​/consignmentId​/{id} Changed /
Query
New optional request parameter "transportEquipmentIdFilter" to filter the resulting events to those associated specifically with the given transport equipment (potentially one of many in the associated consignment).

11/14/2019

API Description Change / Swagger API Notes
GET /api/v1/flowTransactions Removed /
Actionable Flows
This Beta API has been replaced with a POST. Details listed with that new API.
POST /api/v1/flowTransactions New /
Actionable Flows
This Beta API replaces the former GET, enabling more flexibility and adaptability when searching across different trade objects (consignments, transport equipment).
POST /api/v1/actionableMessageFlows/docMessages New /
Actionable Flows
This Beta API performs an action on a document. Example of an action is a VERIFY_COPY document for a SI-BOL flow which needs to be approved or rejected by the Shipper.
GET /api/v1/flowTransactions/{id} Changed /
Actionable Flows
This Beta API has rearranged response attribute providing more information and better organization of the resulting data for the associated trade object.
PUT /api/v1/actionableDocFlows/
- billOfLading
- shippingInstruction
- verifyCopy
Changed /
Actionable Flows
These Beta APIs had their response attribute "tradeObjectIdsIdentifiers" renamed to "tradeObjectIdentifiers".
GET ​/api​/v1​/transportEquipment​/events​/{delegationId} Deprecated /
Query
APIs leveraging delegation IDs are being deprecated and replaced by new APIs leveraging the consignment and transport equipment IDs.
GET ​/api​/v1​/transportEquipment​/splitFromConsignment​/{delegationId} Deprecated /
Query
APIs leveraging delegation IDs are being deprecated and replaced by new APIs leveraging the consignment and transport equipment IDs.
GET ​/api​/v1​/consignments​/delegationIds Deprecated /
Query
APIs leveraging delegation IDs are being deprecated and replaced by new APIs leveraging the consignment and transport equipment IDs.
GET ​/api​/v1​/consignments​/events​/{delegationId} Deprecated /
Query
APIs leveraging delegation IDs are being deprecated and replaced by new APIs leveraging the consignment and transport equipment IDs.
GET /api/v1/consignments/events/consignmentId/{id} New /
Query
Query for consignment events by consignment ID.
GET /api/v1/transportEquipment/events/consignmentId/{id} New /
Query
Query transport equipment events by consignment ID.
GET /api/v1/transportEquipment/events/transportEquipmentId/{id} New /
Query
Query transport equipment events by transport equipment ID.
POST /api/v1/consignments/billOfLadingIssued New /
Event Publish
Convenience API used when a new bill of lading has been issued, enabling the associated creation of a consignment and its assigned transport equipment.
GET /api/v1/partners Updated /
Business Partners
New boolean response field "hasReferences", set to true if there are any non system generated references assigned to the given partnership.

11/05/2019

API Description Change / Swagger API Notes
POST /api/v1/subscriptions/province New /
Subscription
This new API is similar to a country subscription but is scoped to a specific province or emirate.
GET /api/v1/subscriptions

and

GET /api/v1/subscriptions/{id}
Changed /
Subscription
New response attributes for each match in support of the new province subscription type:
"ports" - the array of ports for which the province subscription should receive events.
"provinceEventTypes" - specific event types configured in a province subscription.
GET /api/v1/consignments/creators New /
Event Publish
This new API queries for the names of all organizations that have created consignments for  which the caller has access.
GET /api/v1/consignments Changed /
Query
New request parameter "vehicleName" to find all consignments associated with a specific vehicle by name.

New request header "Accept-Language" to assert the language. of some response fields, where translations are available.

New response attributes:
"bookingData/vehicleName" - The name of the vehicle managing the consignment.
"bookingData/transportEquipmentDetails[]/description" - A description of a piece of equipment within a consignment.
GET /api/v1/consignments/events/{id} Changed /
Query
Several instances of the following response values:
"vehicleName" - The name of the vehicle managing the consignment.
"transportEquipmentDetails[]/description" - A description of a piece of equipment within a consignment.
POST /api/v1/genericEvents/waypoint Changed /
Event Publish
New request parameter "vehicleName" representing the name of the vehicle (vessel, etc.) used to transport the goods.
POST /api/v1/transportEvents/* Changed /
Event Publish
New request parameter "vehicleName" representing the name of the vehicle (vessel, etc.) used to transport the goods.

10/24/2019

API Description Change / Swagger API Notes
POST /api/v1/billOfLadingVerifier/search New /
Financial Services
Only available for financial services organizations, this API allows access to the bill of lading given very specific parameters. The Bill of Lading Verifier solution is sold separately. Contact us at https://tradelens.com/connect if you are interested in purchasing this feature or speaking directly with one of our sellers.
GET /api/v1/transportEquipment/splitFromConsignment/{id} New /
Query
Get the transport summery for a piece of transport equipment that was split from a consignment given a delegation ID.
GET /api/v1/consignments/delegationIds Changed /
Query
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to find a specific consignment.
GET /api/v1/transportEquipment/delegationIds Changed /
Query
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to find a specific consignment.
GET /api/v1/consignments Changed /
Query
New response attributes:
"splitFromConsignment" - with several sub-fields describing the consignment from which the given consignment was split.
"formerlyAssociatedTransportEquipment" - an array with a list of transport equipment IDs that were formerly associated with this consignment, but were removed per a split bill of lading, and have not been associated with a new consignment yet.
GET /api/v1/consignments Changed /
Query
New response attributes:
"combinedConsignments" - array of consignments which have been combined into the current consignment.
"combinedIntoConsignment" - with several fields describing the consignment that the current consignment was combined into.
GET /api/v1/consignments/events/{id} Changed /
Query
New response attribute for applicable events returned:
"splitFromConsignment" - with several sub-fields describing the consignment from which the given consignment was split.
GET /api/v1/transportEquipment/events/{id} Changed /
Query
New response attribute for applicable events returned:
"splitFromConsignment" - with several sub-fields describing the consignment from which the given consignment was split. 
POST /api/v1/consignments/
- consignmentSubcontracted
- partyAdded
- referenceAdded
- statusUpdated
Changed /
Event Publish
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments.
POST /api/v1/consignments/consignmentSubcontracted Changed /
Event Publish
New request parameter "subcontractBOL" representing the bill of lading number of the child consignment. This is needed to isolate a subcontracted consignment if it is associated with a bill of lading.
POST /api/v1/genericEvents/ Changed /
Event Publish
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments.
POST /api/v1/genericEvents/cutOffTime Changed /
Event Publish
Request parameter "cutOffEventType" is now an optional field, whereas formerly it was required.
POST /api/v1/transportEvents/ Changed /
Event Publish
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments.
POST /api/v2/consignments Changed /
Event Publish
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments.
POST /api/v2/consignments Changed /
Event Publish
New request parameter "combinedCarrierBookingNumbers" is an array of carrier booking numbers referring to consignments (bookings) that are being combined into the current consignment.
POST /api/v2/transportEquipment Changed /
Event Publish
New request parameters:
"billOfLadingNumber" - as part of support for split consignments, enabling users to identify specific consignments.
"transferFromEquipment" - as part of supporting the transfer of equipment from one consignment to another in the booking stage.
POST /api/v1/subscriptions/delegationId Deprecated /
Subscription
This API is being deprecated in favor of using organization level subscriptions.
GET /api/v1/transactions Deprecated /
Document Sharing
This API is being replaced by the new v2 version below.
GET /api/v2/transactions New /
Document Sharing
This API is replacing the old v1 (now deprecated) API to fetch outstanding transactions. It has been enhanced to support pagination.

09/17/2019

API Description Change / Swagger API Notes
POST /api/v2/transportEquipment Changed /
Event Publish
New request parameter "transferFromConsignment" including values for "carrierBookingNumber", "billOfLadingNumber", and "consignmentId". When provided, the given piece of equipment will be transferred from the provided consignment.
POST /api/v1/transportEvents/* Changed /
Event Publish
The "transportationPhase" field was formerly required but is now optional.

09/05/2019

API Description Change / Swagger API Notes
GET /api/v1/consignments Changed /
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 New /
Business Partners
List the business partners and requests for the current organization.
POST /api/v1/partners New /
Business Partners
Send business partner requests to a list of organizations.
PATCH /api/v1/partners New /
Business Partners
Change the status of multiple business partner requests.
GET /api/v1/profile/organization New /
Business Partners
Returns the organization's Business Partner profile.
PATCH /api/v1/profile/organization New /
Business Partners
Updates the organization's Business Partner profile.
GET /api/v1/organizations New /
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 Changed /
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 Changed /
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 Changed /
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} Changed /
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 Removed /
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 Removed /
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 Changed /
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} Changed /
Query
New response attribute "status" for each consignment, representing its current state ("Active" or "Canceled").
POST /api/v1/tradeObjectIds Changed /
Query
New optional response attribute "relatedTradeObjectIds", an  array of additional unique trade object identifiers.
PUT /api/v1/actionableDocFlows/shippingInstruction Changed /
Actionable Flows
(Beta) The response attribute, "carrierOrgId" was removed.
PUT /api/v1/actionableDocFlows/verifyCopy New /
Actionable Flows
(Beta) Triggers the actionable flow associated with the Verify Copy structured document. 
GET /api/v1/flowTransactions Changed /
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} Changed /
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 Changed /
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 Changed /
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
Changed /
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}
Changed /
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 Changed /
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} Changed /
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/* Removed /
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 Changed /
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 Changed /
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} Changed /
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} Changed /
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 New /
Event Publish
To support consignment hierarchies, this allows a relationship to be established between a consignment and its subconsignment.
POST /api/v1/consignments/transportEquipmentAdded Deprecated /
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 Changed /
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} Changed /
Query
New response field "description" is returned as part of the location of an event.
GET /api/v1/transportEquipment/events/{id} Changed /
Query
New response field "description" is returned as part of the location of an event.
GET /api/v1/consignments/transportSummaries/{id} Changed /
Query
New response field "description" is returned as part of several location objects.
GET /api/v1/transportEquipment/transportSummaries/{id} Changed /
Query
New response field "description" is returned as part of several location objects.
PUT /api/v1/actionableDocFlows/billOfLading New /
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 New /
Actionable Flows
Parse a Shipping Instructions JSON document and handle the associated creation and setup of consignments and transport equipment.
GET /api/v1/flowTransactions New /
Actionable Flows
Fetch all actionable flow transactions.
GET /api/v1/flowTransactions/{id} New /
Actionable Flows
Fetch a specific actionable flow transaction.
GET /api/v1/documentSchema Deprecated /
Document Sharing
Deprecated in favor of the new V2 version of the API.
GET /api/v2/documentSchema New /
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 Deprecated /
Document Sharing
Deprecated in favor of the new V2 version of the API.
GET /api/v2/documents/{id}/metadata New /
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 Deprecated /
Document Sharing
Deprecated in favor of the new V2 version of the API.
POST /api/v2/documents/bulk/documents New /
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 Deprecated /
Document Sharing
Deprecated in favor of the new V2 version of the API.
POST /api/v2/documents/search New /
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 Deprecated /
Document Sharing
Deprecated in favor of the new V2 version of the API.
PUT /api/v2/documents New /
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.