API Documentation (Swagger API URLs and API Release Notes)
Copyright IBM Corporation and GTD Solution Inc. 2018, 2020
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, and review the API User Guide.
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
10/29/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/transportEvents/planned* (all planned events) |
Event Publish |
The "eventOccurrenceTime8601" field was formerly required and is now optional. The "transportPlanSequenceNumber" field is now mandatory. Typically this would be viewed as a breaking API change, but the providers of these events have been notified/reviewed and there is no exposure. |
| POST /api/v1/documentEvents | Event Publish |
Document events will now be published with a new field "releaseParty" when applicable and related to actionable flows. |
| GET /api/v1/consignments/events/ consignmentId/{id} |
Trade Object |
New response JSON attribute "releaseParty" added for affected document events, including "partyRef", "orgName", and "address" information. New response attribute "transportPlanSequenceNumber" has been added for transport plan events. |
| GET /api/v1/shipments/{id}/events | Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ events/consignmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ events/transportEquipmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/unassociatedEvents | Trade Object |
Same as above. |
| GET /api/v1/consignments/ transportSummaries/ consignmentId/{id} |
Trade Object |
New response attribute "transportPlanSequenceNumber" has been added for transport plan events. |
| GET /api/v1/transportEquipment/ currentProgress/ consignmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ currentProgress/ splitFromConsignment/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ currentProgress/ transportEquipmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ transportSummaries/ consignmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ transportSummaries/ splitFromConsignment/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/ transportSummaries/ transportEquipmentId/{id} |
Trade Object |
Same as above. |
10/21/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/actionableFlows/search | Actionable Flows |
The "tradeObjectIdentifiers" field has been changed to an array to enable more extensive searches. While this is technically a breaking change, verification is being done to ensure all existing callers are prepared. |
| GET /api/v2/consignments | Trade Object |
Each of the following existing request fields now support a comma delimited list of values: - carrierBookingNumber - billOfLadingNumber - equipmentNumber |
| GET /api/v1/alerts | Notifications and Alerts |
The "messageParams" object in the response includes the following two new fields, each of which is found in the event that triggered the associated alert: - originatorName - originatorId In addition, several new optional query parameters are available to filter an alert search. |
| GET /api/v1/alerts/{id} | Notifications and Alerts |
The "messageParams" object in the response includes the following two new fields, each of which is found in the event that triggered the associated alert: - originatorName - originatorId |
| GET /api/v1/consignments | Trade Object |
The response contains a new "currentData" object with elements similar to "bookingData". The new fields are meant to represent the most current view of the data, starting with booking data but later being updated by transport plan updates. Note: this current data will now be rendered in the UI's consignment summary in place of booking data. |
| GET /api/v2/consignments | Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/consignments/ transportSummaries/ consignmentId/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ currentProgress/ consignmentId/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ currentProgress/ splitFromConsignment/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ currentProgress/ transportEquipmentId/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ transportSummaries/ consignmentId/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ transportSummaries/ splitFromConsignment/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
| GET /api/v1/transportEquipment/ transportSummaries/ transportEquipmentId/{id} |
Trade Object |
See above regarding the new "currentData" field returned in the response. |
09/30/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| PATCH /api/v1/alerts/{id} | Notifications & Alerts |
Patch the flags (read, flagged, deleted) of an alert by id for the logged in user. |
| POST /api/v1/actionableFlows/search | Actionable Flows |
The "tradeObjectIdentifiers" field has been changed to an array to enable more extensive searches. While this is technically a breaking change, verification is being done to ensure all existing callers are prepared. |
09/21/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v2/transportEquipment | Event Publish |
A new request parameter, "partLoadWithConsignment" allows the caller to associate/share a piece of transport equipment with another consignment. This was created to aid in part load scenarios in the booking stage. |
| GET /api/v1/consignments/events/ consignmentId/{id} |
Trade Object |
The response now includes details with the following extra fields associated with events returned: - "partLoadWithConsignment" - details about a consignment involved in part load scenario. - "transferFromConsignment" - details about a consignment from which pieces of equipment have been transferred. - "transferFromEquipment" - This is an equipment number of a piece of transport equipment that will be updated with the equipment number specified by "equipmentNumber" field. |
| GET /api/v1/shipments/{id}/events | Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/events/ consignmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/transportEquipment/events/ transportEquipmentId/{} |
Trade Object |
Same as above. |
| GET /api/v1/unassociatedEvents | Trade Object |
Same as above. |
| GET /api/v2/consignments | Trade Object |
The response now includes "consignmentUpdateFromBOLTime" representing the submission time of the "billOfLadingIssued" or "verifyCopyIssued" event that most recently updated the consignment. |
| GET /api/v1/consignments/ consignmentId/{id} |
Trade Object |
Same as above. |
| GET /api/v1/organizations/entitlements | Organization Admin |
This new API returns the list of entitlements for the calling organization. Entitlements are features that were enabled for the organization by the TradeLens onboarding team; for example Bill of Lading Verifier. |
09/03/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v1/documentActions | Platform Constants |
This API has been deprecated in favor of a the new version below. |
| GET /api/v2/documentActions | Platform Constants |
This new v2 API returns the list of actions applicable to documents in Actionable Flows. |
| GET /api/v1/alerts | Notifications & Alerts |
List all alerts for the requesting user. |
| GET /api/v1/alerts/{id} | Notifications & Alerts |
Get a specific alert by ID. |
08/24/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/actionableFlows/search | Actionable Flows |
The new boolean request parameter "includeActionAuditList" is available. When set to true, the API will fetch the audit action list for the eBL flow. The default is false. Similarly, the API response now includes an "actionAuditList". |
08/06/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/transportEquipment/ cargoTypeUpdated |
Event Publish |
Optional field "consignmentId" was removed as a parameter in the event body, aligning with other transport equipment admin events. It was not being used before, but carrierBookingNumber and billOfLadingNumber are still available. |
| GET /api/v1/unassociatedEvents | Trade Object |
Several new request parameters have been added to aid in filtering the response. |
| PUT /api/v1/user/preferences | User Preferences |
Note: This API is still Beta. Specification of contacts has been simplified. |
| PATCH /api/v1/user/preferences | User Preferences |
Note: This API is still Beta. Specification of contacts has been simplified. |
| DELETE /api/v1/user/preferences | User Preferences |
Note: This API is still Beta. A specific contactId can now be provided in a query parameter to do selective deletion. |
| POST /api/v1/alertSubscriptions | Notifications and Alerts |
Note: This API is still Beta. The request location "type" field has transitioned from an optional to a required field. |
| PUT /api/v1/alertSubscriptions/{id} | Notifications and Alerts |
Note: This API is still Beta. The request location "type" field has transitioned from an optional to a required field. |
| GET /api/v1/alertSubscriptions | Notifications and Alerts |
Note: This API is still Beta. The response location "type" field has transitioned from an optional to a required field. |
| POST/GET/PUT/DELETE /api/v1/ customerRecords/* |
Carrier |
This functionality is covered elsewhere in the Business Partners API. |
| POST /api/v1/routeRecords | Carrier |
Enable the configuration of origin and destination "routes" associated with a business partner and type of transportation (barge, rail, truck, vessel). It will be matched against new transport plans from the ocean carrier to grant automatic visibility to the business partner (vs sending a partyAdded event). |
| GET /api/v1/routeRecords | Carrier |
Fetch the configured routes (see above) for the ocean carrier. |
| DELETE /api/v1/routeRecords/{id} | Carrier |
Delete a specific route configured for the ocean carrier. |
| PATCH /api/v1/routeRecords/{id} | Carrier |
Update a specific route configured for the ocean carrier. |
07/23/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| PUT /api/v1/actionableDocFlows/billOfLading | Actionable Flows |
New optional "metadata" field in the body is now available with underlying "docIssuanceTime" enabling the platform to ignore older, out of order, document uploads. |
| PUT /api/v1/actionableDocFlows/ shippingInstruction |
Actionable Flows |
New optional "metadata" field in the body is now available with underlying "docIssuanceTime" enabling the platform to ignore older, out of order, document uploads. |
| PUT /api/v1/actionableDocFlows/verifyCopy | Actionable Flows |
New optional "metadata" field in the body is now available with underlying "docIssuanceTime" enabling the platform to ignore older, out of order, document uploads. |
| PATCH /api/v1/user/preferences | User Preferences |
Several fields (and sub-fields) of this Beta API are now marked as mandatory. |
07/13/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| PUT /api/v1/partners/bulk | Business Partners |
Upload a CSV file to update partnership references. |
| POST /api/v1/actionableMessageFlows/ docMessages |
Actionable Flows |
In support of the new "Switch to Paper" feature, a new action identifier, "eBLSwitchToPaper", exists as a request parameter and in the API response. |
| GET /api/v1/consignments/events/ consignmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/consignments/ transportSummaries/consignmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/shipments/{id}/events | Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ currentProgress/consignmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ currentProgress/splitFromConsignment/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ currentProgress/transportEquipmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/events/ consignmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/events/ transportEquipmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ transportSummaries/consignmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ transportSummaries/splitFromConsignment/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/transportEquipment/ transportSummaries/transportEquipmentId/{id} |
Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
| GET /api/v1/unassociatedEvents | Trade Object |
A new response field "eventPriority" has been added to responses for several APIs identifying the priority of a given event, considering the sender. |
06/29/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v1/alertTypes | Notifications & Alerts |
List the various alert types. This is leveraged by the Notifications and Alerts feature. |
| POST /api/v1/alertSubscriptions | Notifications & Alerts |
Create a new alert subscription. This is leveraged by the Notifications and Alerts feature. |
| GET /api/v1/alertSubscriptions | Notifications & Alerts |
List configured alert subscriptions. This is leveraged by the Notifications and Alerts feature. |
| PUT /api/v1/alertSubscriptions/{id} | Notifications & Alerts |
Replace an existing alert subscription. This is leveraged by the Notifications and Alerts feature. |
| DELETE /api/v1/alertSubscriptions/{id} | Notifications & Alerts |
Delete an existing alert subscription. This is leveraged by the Notifications and Alerts feature. |
| PUT /api/v1/user/preferences | User Preferences |
Create and update new user preferences. This is leveraged by the Notifications and Alerts feature. |
| GET /api/v1/user/preferences | User Preferences |
Fetch the user preference configuration. This is leveraged by the Notifications and Alerts feature. |
| DELETE /api/v1/user/preferences | User Preferences |
Delete the user preference configuration. This is leveraged by the Notifications and Alerts feature. |
| PATCH /api/v1/user/preferences | User Preferences |
Updates existing user preferences. This is leveraged by the Notifications and Alerts feature. |
| POST /api/v1/transportEvents/ genericTransportEvent |
Event Publish |
This new transport event is a convenience for event publishers. It is a consolidated version of all planned, estimated, and actual events. They can now all be sent through this single API, specifying the details within the payload fields. Note, this event will not be published as is at this time (to prevent impact to existing customer subscriptions). Rather, it will be converted to the existing/old style transport events so back-end consumption is seamless. |
| GET /api/v1/unlocodes | Platform Constants |
This new utility API will return a un/locode value based on an input location string, helpful in several scenarios. |
| GET /api/v1/transportEquipment/ currentProgress/* |
Trade Object |
New optional field/array, "cargoTypes", has been added to the response, specific to consignment details. Each element of the array includes a "code" and a "description". This adds extra information about the consignment not formerly available in these APIs. |
| GET /api/v1/transportEquipment/ transportSummaries/* |
Trade Object |
New optional field/array, "cargoTypes", has been added to the response, specific to consignment details. Each element of the array includes a "code" and a "description". This adds extra information about the consignment not formerly available in these APIs. |
06/02/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| GET /api/v1/partners | Business Partners |
New response array field, "organizationTypes", has been added including the list of organization types associated with each business partner in the list. |
05/20/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/consignments/ verifyCopyIssued |
Event Publish |
This is a new internally generated event representing that a verify copy document was uploaded in association with a consignment. |
| POST /api/v1/consignments/ billOfLadingIssued |
Event Publish |
A new optional boolean request field "partBill" can be provided indicating a bill of lading represents a part bill. |
| POST /api/v1/genericEvents/ temperatureSetPoint |
Event Publish |
New request fields have been added to enable this event to represent more information about the temperature of a container. - minimumTemperature - maximumTemperature - units - temperatureInstructions |
| POST /api/v1/genericEvents/ temperatureUpdated |
Event Publish |
New request fields have been added to enable this event to represent more information about the temperature of a container. - minimumTemperature - maximumTemperature - units - temperatureInstructions |
| GET /api/v1/transportEquipment/ currentProgress/consignmentId/{id} |
Trade Object |
Get the current progress for one or more pieces of transport equipment associated with a consignment. This progress is presented by a list of transport events divided into three categories (planned, estimated, actual) ordered by the sequence in which they occur. |
| GET /api/v1/transportEquipment/ currentProgress/splitFromConsignment/{id} |
Trade Object |
Get the current progress for one or more pieces of transport equipment that were split from the consignment with the given consignment ID. This progress is presented by a list of transport events divided into three categories (planned, estimated, actual) ordered by the sequence in which they occur. |
| GET /api/v1/transportEquipment/ currentProgress/transportEquipmentId/{id} |
Trade Object |
Get the current progress for a specific piece of transport equipment. This progress is presented by a list of transport events divided into three categories (planned, estimated, actual) ordered by the sequence in which they occur. |
| GET /api/v1/consignments and GET /api/v2/consignments |
Trade Object |
New response fields can be provided indicating information that a consignment represents a part bill. The following fields are provided as part of the new "partBillOf" JSON object. - carrierBookingNumber - billOfLadingNumber - consignmentId |
| All APIs that return events | Trade Object |
New response fields can be provided indicating an event includes part bill information. In these cases, a boolean "partBill" flag will be set to true. In addition, a "partBillOf" JSON object will be provided with the following fields. - carrierBookingNumber - billOfLadingNumber - consignmentId |
| POST /api/v1/tradeObjectIds | Trade Object |
A new response field "creationTime" is now included for each trade object returned, indicating when that trade object was created. |
| PUT /api/v1/organizations/users/{id} | Organization Admin |
Updates an existing user for the organization. |
| DELETE /api/v1/organizations/users/{id} | Organization Admin |
Deletes the specified user associated with the organization. |
| POST /api/v1/organizations/users | Organization Admin |
Creates a new user for the organization. |
| GET /api/v1/organizations/users | Organization Admin |
Lists all the users of the organization. |
| POST /api/v1/actionableFlows/search | Actionable Flows |
A new optional request field, "includeInactive" (default false), has been added to enable the caller to include inactive flows in the response or not. Also, some response fields have been removed from the (Beta) API response: - "SIToBillFlow" JSON, including fields "carrierName" and "scacCode" - "objectRef" field, that is part of the "actionObjects" array |
05/07/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/actionableFlows/search | Actionable Flows |
This Beta API has the following changes: - The request field "includeInactive" has been removed. - New response fields have been added: flowTypeAttributes -> SIToBillFlow (carrierName and scacCode) and actionObjects->objectRef. |
| All events involving the address field. | Event Publish |
The following request parameters within location related fields were formerly required, but are now optional: - address1 - stateProvince - zipPostal |
| GET /api/v1/unassociatedEvents | Trade Object |
This new API can be used for debugging in order to find events that were published to TradeLens, but have not been associated with a trade object (shipment, consignment, or transport equipment). These events may have been set aside (orphaned) until a matching trade object is created, or there may be something errant in the event which will prevent it from ever matching. |
| GET /api/v2/consignments | Trade Object |
There is a new optional request parameter "latestPlanIssuedInLastNDays", used as a filter to show the latest set of planned events sent to this consignment having a transportPlanIssuanceTime between now and a given number of days ago. |
04/20/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/actionableFlows/{id}/nextActions | Actionable Flows |
Query all Next actions for a given flow instance ID. |
| PUT /api/v1/partners | Business Partners |
Replace references associated with a particular partner ID. |
| DELETE /api/v1/partners | Business Partners |
Delete the specified reference from the business partnership. |
| GET /api/v1/partners | Business Partners |
New response field, "displayName", representing an alias name for the partner ID. |
| POST /api/v1/consignments/ transportEquipmentRemoved |
Event Publish |
Disassociates the transport equipment from the consignment. |
| All events that include a "location" field. | Event Publish |
There are multiple changes to the "location" request parameter, enabling more flexibility for event publishers. Furthermore, multiple value formats can be provided in the same event. - The existing "type" and "value" fields are no longer required, but when not provided, one of the new fields must be supplied. - There is a set of fields to provide location information: - unlocode (string) - address (JSON structure) - smdgTerminal (string) - geoCoord (latitude and longitude numbers) - splc (string) - gln (string) |
| POST /api/v2/consignments | Event Publish |
Similar to the location field changes specified above, the request parameters "bookingData" has two fields affected the same way: "originLocation" and "destinationLocation". |
| POST /api/v1/genericEvents/customsHold | Event Publish |
New request parameter "consignmentId" provided to associate the event with a consignment by ID. |
| POST /api/v1/genericEvents/customsRelease | Event Publish |
New request parameter "consignmentId" provided to associate the event with a consignment by ID. |
| GET /api/v1/subscriptions | Event Subscription |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v1/subscriptions/{id} | Event Subscription |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v1/consignments/delegationIds | Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/consignments/events/ {delegationId} |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/consignments/ transportSummaries/{delegationId} |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/transportEquipment/ delegationIds |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/transportEquipment/ events/{delegationId} |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/transportEquipment/ splitFromConsignment/{delegationId} |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/transportEquipment/ transportSummaries/{delegationId} |
Trade Object |
This API has been deprecated for a while and is now being hidden from Swagger. It will continue to work for at least one more month before support is removed. |
| GET /api/v1/consignments | Trade Object |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v2/consignments | Trade Object |
New optional request parameters to enable additional filtering: - onWater - transshipment - startChangeInVesselArrivalFromFirstPlan - endChangeInVesselArrivalFromFirstPlan - startLatestPlanIssuanceTime - endLatestPlanIssuanceTime Also, the response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| All Trade Object APIs that return a "location" field. | Trade Object |
See earlier comments made about all events being published to the TradeLens platform. The same details apply. |
| GET /api/v1/consignments/events/ consignmentId/{id} |
Trade Object |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v1/shipments/{id}/events | Trade Object |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v1/transportEquipment/ events/consignmentId/{id} |
Trade Object |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
| GET /api/v1/transportEquipment/ events/transportEquipmentId/{id} |
Trade Object |
The response JSON object no longer includes a "delegationId" as that has been phased out across the TradeLens API. |
03/31/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/consignments/ billOfLadingNumberAvailable |
Event Publish |
Updates the consignment with the bill of lading number if it does not have one. This enables other events (to be sent with the bill of lading number) to be properly matched with a consignment during the window of time before the bill of lading is issued. |
| POST /api/v1/documentEvents | Event Publish |
This is shown in Swagger exclusively for the purpose of helping subscribers understand the schema of the events that will be published. This API cannot be called and will return an error. These events are published within TradeLens when documents are uploaded through Document Sharing or Actionable Flows APIs. |
| POST /api/v1/genericEvents/ containerReadyForPickup |
Event Publish |
This event signals that one or more pieces of transport equipment are available to be picked up from a location via truck, notifying the involved actors of availability. |
| POST /visibility/v1/events/ - E041 - E044 - E269 - E408 - E431 - E434 - E449 |
Event Publish |
These events have been deprecated for a long time and are now being hidden from Swagger. They will continue to function for at least one month, and then the endpoints will be removed completely. |
| POST /api/v1/consignments/ billOfLadingIssued |
Event Publish |
A new optional request parameter "eBLProvider" has been added. That value should be set to the name of the electronic bill of lading provider. The eBLProvider field will be used by non TradeLens e-BL systems to notify that an e-BL (outside of TradeLens) was issued for this consignment. |
| POST /api/v1/genericEvents/ billOfLadingSurrendered |
Event Publish |
A new optional request parameter "consignmentId" has been added, as an alternate way to associate the event with a consignment (formerly just carrierBookingNumber and billOfLadingNumber). |
| POST /api/v1/genericEvents/customsHold | Event Publish |
A new optional request parameter "reasonCode" has been added as a string representation of the reason for the customs hold. |
| All Trade Object APIs | Trade Object |
More clearly defined HTTP errors response codes. Here is the documented list now: - 403 - Forbidden - 404 - Not Found - 429 - Too Many Requests |
| GET /api/v1/consignments/events/ consignmentId/{id} |
Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
| GET /api/v1/consignments/events/{id} | Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
| GET /api/v1/shipments/{id}/events | Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
| GET /api/v1/transportEquipment/events/ consignmentId/{id} |
Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
| GET /api/v1/transportEquipment/events/ transportEquipmentId/{id} |
Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
| GET /api/v1/transportEquipment/events/{id} | Trade Object |
Two new attributes are included in successful responses, as part of an event returned within an array: - eBLProvider - reasonCode |
03/19/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/genericEvents/customsHold | 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 | Event Publish |
New event to recognize that the verified gross mass (VGM) has been received. |
| POST (several) | 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 | Platform Constants |
Returns list of supported roles in TradeLens. |
| GET /api/v1/documentTypes | Platform Constants |
Returns list of supported document types in TradeLens. |
| GET /api/v1/documentActions | Platform Constants |
Returns list of supported document actions in TradeLens. |
03/05/2020
| API Description | Change / Swagger API | Notes |
|---|---|---|
| POST /api/v1/actionableFlows | Actionable Flows |
Query all actionable flows based document type and trade object identifiers. |
| POST /api/v1/actionableFlows/search | 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 | Event Subscription |
Publish a test event to a webhook. |
| POST /api/v1/subscriptions/{id}/disable | Event Subscription |
Manually disable the given subscription. |
| POST /api/v1/subscriptions/{id}/enable | Event Subscription |
Manually enable the given subscription. |
| POST /api/v1/subscriptions/{id}/status | 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 | 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 |
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 | 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} | Actionable Flows |
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId". |
| PUT /api/v1/actionableDocFlows/ billOfLading |
Actionable Flows |
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId". |
| PUT /api/v1/actionableDocFlows/ shippingInstruction |
Actionable Flows |
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId". |
| PUT /api/v1/actionableDocFlows/ verifyCopy |
Actionable Flows |
New response attributes are now available to support the shipment trade object: "reference", reference "type" and "shipmentId". |
| POST /api/v1/shipments | Event Publish |
As part of the new shipments feature, this event represents the creation of a shipment. |
| POST /api/v1/shipments/ consignmentAdded |
Event Publish |
As part of the new shipments feature, this event associates a shipment with a consignment. |
| POST /api/v1/shipments/ partyAdded |
Event Publish |
As part of the new shipments feature, this event grants visibility of a party to a shipment. |
| POST /api/v1/shipments/ partyListUpdated |
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 |
Event Publish |
As part of the new shipments feature, this event removes visibility of a party to a shipment. |
| POST /api/v1/shipments/ referenceAdded |
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 |
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 |
Event Publish |
As part of the new shipments feature, this event removes a reference from a shipment. |
| POST /api/v1/consignments/ partyListUpdated |
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 |
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 |
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 |
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 |
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 | Trade Object |
Search for shipments based on various matching fields. |
| GET /api/v1/shipments/creators | 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 | Trade Object |
Fetch all the events for a given shipment. |
| POST /api/v1/tradeObjectIds | 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} |
Trade Object |
Consignments in the response will now include the "billOfLadingNumber" if applicable. |
| GET /api/v1/transportEquipment/ transportSummaries/consignmentId/{id} |
Trade Object |
Consignments in the response will now include the "billOfLadingNumber" if applicable. |
| GET /api/v1/transportEquipment/ transportSummaries/splitFromConsignment/{id} |
Trade Object |
Consignments in the response will now include the "billOfLadingNumber" if applicable. |
| GET /api/v1/transportEquipment/ transportSummaries/transportEquipmentId/{id} |
Trade Object |
Consignments in the response will now include the "billOfLadingNumber" if applicable. |
| GET /api/v1/transportEquipment/ transportSummaries/{id} |
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 | 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 | Actionable Flows |
New API to fetch actionable flows based on the flow type and trade object identifier. |
| POST /api/v1/actionableMessageFlows/docMessages | 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 | 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 | 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/{} |
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/{} | 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/{} |
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/{} |
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/{} |
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 |
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 |
Event Publish |
Enables the removal of consignment. references formerly added by the caller. |
| POST /api/v1/transportEquipment/ referenceListUpdated |
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 |
Event Publish |
Enables the removal of transport equipment references formerly added by the caller. |
| POST /api/v2/consignments/referenceAdded | 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 |
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 |
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 |
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 |
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} |
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} |
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} |
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} |
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} |
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} |
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} |
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 |
Event Publish |
Two roles were removed: "TRANSPORT_SERVICE_INTERMEDIARY", "DATA_AGGREGATOR". |
| POST /api/v1/transportEquipment/ partyAdded |
Event Publish |
Two roles were removed: "TRANSPORT_SERVICE_INTERMEDIARY", "DATA_AGGREGATOR". |
| POST /api/v1/transportEquipment/ partyListUpdated |
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 |
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 |
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 |
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 |
Event Publish |
Note that a bill of lading has been surrendered to the carrier. |
| GET /api/v1/partners | 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 | Actionable Flows |
Fetch all actionable flows by flow type. (Sandbox zone 01/29/2020, Production zone 02/10/2020) |
| POST /api/v1/actionableMessageFlows/docMessages | 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 | Document Sharing |
Fetch a document's printable content, if available. |
| GET /api/v2/documents/{documentId}/metadata | 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 | Actionable Flows |
New optional request field "printableCopy" used to upload the printable copy for the Verify Copy document. |
| PUT /api/v1/actionableDocFlows/billOfLading | 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} | 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 | Actionable Flows |
This Beta API has been replaced with a POST. Details listed with that new API. |
| POST /api/v1/flowTransactions | 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 | 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} | 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 |
Actionable Flows |
These Beta APIs had their response attribute "tradeObjectIdsIdentifiers" renamed to "tradeObjectIdentifiers". |
| GET /api/v1/transportEquipment/events/{delegationId} | 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} | 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 | 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} | 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} | Query |
Query for consignment events by consignment ID. |
| GET /api/v1/transportEquipment/events/consignmentId/{id} | Query |
Query transport equipment events by consignment ID. |
| GET /api/v1/transportEquipment/events/transportEquipmentId/{id} | Query |
Query transport equipment events by transport equipment ID. |
| POST /api/v1/consignments/billOfLadingIssued | 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 | 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 | 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} |
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 | 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 | 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} | 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 | Event Publish |
New request parameter "vehicleName" representing the name of the vehicle (vessel, etc.) used to transport the goods. |
| POST /api/v1/transportEvents/* | 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 | 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} | 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 | Query |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to find a specific consignment. |
| GET /api/v1/transportEquipment/delegationIds | Query |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to find a specific consignment. |
| GET /api/v1/consignments | 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 | 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} | 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} | 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 |
Event Publish |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments. |
| POST /api/v1/consignments/consignmentSubcontracted | 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/ |
Event Publish |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments. |
| POST /api/v1/genericEvents/cutOffTime | Event Publish |
Request parameter "cutOffEventType" is now an optional field, whereas formerly it was required. |
| POST /api/v1/transportEvents/ |
Event Publish |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments. |
| POST /api/v2/consignments | Event Publish |
New request parameter "billOfLadingNumber" as part of support for split consignments, enabling users to identify specific consignments. |
| POST /api/v2/consignments | 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 | 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 | Subscription |
This API is being deprecated in favor of using organization level subscriptions. |
| GET /api/v1/transactions | Document Sharing |
This API is being replaced by the new v2 version below. |
| GET /api/v2/transactions | 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 | 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/* | 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 | 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. |