This article will explain how to use the ShipmentData API to search and load shipments. It will explain the possible parameters and list the different methods used.
The ShipmentData API will replace the old Portal Data WS. The ShipmentData API is a REST API and uses tokens for authentication. It has improved performance, is more scalable, and is built using a more secure technology compared to the old webservice. The ShipmentData API can be used to retrieve data from the past 12 months.
Our recommendation for all Portal Apis is to use the HTTPS (version TLS 1.2 minimum) in order to function properly and have enhanced security. Support for TLS 1.0 and 1.1 will be deprecated in the future. TLS 1.0 and 1.1 are out-of-date protocols that do not support modern cryptographic algorithms, and they contain security vulnerabilities that may be exploited by attackers.
Go to:
Authentication and HTTP responses
Using the API requires the use of tokens (Client IDs and Client Secrets). The authorization and authentication are compliant with OAuth2 and all the methods of the public API will have an authorization token (access_token) in the HTTP Header.
To learn how to create a token, please read this article: API configuration setup.
Choose public_api_portal_shipment_data under Allowed scopes for the ShipmentData API.
Endpoint
https://customer-api.consignorportal.com/ApiGateway/ShipmentData
This is a REST API and can only be used for sending/receiving requests so is not meant to be opened in a browser.
Meaning of HTTP status codes:
HTTP Status Code - 200 OK --> Data successfully received and is sent for processing
HTTP Status Code - 401 Unauthorized --> Not valid credentials
HTTP Status Code - 400 Bad Request --> Invalid input data
HTTP Status Code - 500 InternalServerError --> Unknown error
HTTP Status Code - 429 Too many requests --> Exceeded the limit of calls per minute. The limit is set according to the customer's subscription.
Parameters
|
shipmentUuid |
|
This is the universally unique identifier for identifying a Shipment. |
|
Type: string |
|
MinLength: 36 |
|
MaxLength: 36 |
|
Required: Yes |
|
packageUuid |
|
This is the universally unique identifier for identifying a package. |
|
Type: string |
|
MinLength: 36 |
|
MaxLength: 36 |
|
Required: Yes |
|
binaryUuid |
|
This is the universally unique identifier for identifying a document attached to a shipment. |
|
Type: string |
|
MinLength: 36 |
|
MaxLength: 36 |
|
Required: Yes |
|
query |
|
The item you are searching for. This could a barcode, a pickup code or an order number. Note that you must include the entire string, not just a partial barcode or order number. |
|
Type: string |
|
MinLength: 3 |
|
MaxLength: 36 |
|
Required: Yes |
|
Restrictions and validations: - Must not be null. Must be at least 3 characters long. |
|
startDate |
|
The start of the date range interval by which we search for shipments - by default, it will be the current date and time minus 31 days. |
|
Type: DateTimeOffset (example: "2022-08-08T09:07:53+03") |
|
Min: CurrentDate minus 365 days |
|
MaxValue: EndDate |
|
Required: Yes |
|
Restrictions and validations: - No more than 365 days old - No more than 31 days old compared to the endDate. - In case of querying by date range, the startDate should be no more than 24h old compared to the endDate. - If no offset is provided it is automatically set to 00. |
|
endDate |
|
The end of the date range interval by which we search for shipments - by default it will be the current date and time. |
|
Type: DateTimeOffset (example: "2022-08-08T09:07:53+03") |
|
Min: CurrentDate minus 334 days |
|
Max: N/A |
|
Required: Yes |
|
Restrictions and validations: - Must be greater than startDate, but no more than 24h (query by date range) or 31 days (query by pickup code, order number, barcode). - If no offset is provided it is automatically set to 00. |
|
pageSize |
|
The number of items to retrieve in one batch - default is 20. |
|
Type: integer |
|
Min: 1 |
|
Max: 100 |
|
Required: Yes |
|
pageIndex |
|
Zero-based results batch index. |
|
Type: integer |
|
Min: 0 |
|
Max: N/A |
|
Required: Yes |
|
dataRangeSource |
|
Determines the date field to query by in case of a data range lookup. Values can be: 1 - submit date 2 - date modified |
|
Type: integer |
|
Min: 1 |
|
Max: 2 |
|
Required: only on date range query |
|
installationTags |
|
Collection of installation identifiers to be applied on search. |
|
Type: string[] |
|
MinLength: 0 |
|
MaxLength: N/A - should only be as many as the user has access to. |
|
Required: No |
|
actorTags |
|
Collection of actor identifiers to be applied on search. |
|
Type: string[] |
|
MinLength: 0 |
|
MaxLength: N/A - should only be as many as the user has access to |
|
Required: No - if the user performing the search is a customer user, and no actors list is supplied, this will be defaulted in the backend by the list of actors the user has access to. |
|
carrierTags |
|
Collection of carrier identifiers to be applied on search. |
|
Type: string[] |
|
MinLength: 0 |
|
MaxLength: N/A - should only be as many as the user has access to |
|
Required: No - if the user performing the search is a carrier user, and no carriers list is supplied, this will be defaulted in the backend by the list of carriers the user has access to. |
Methods
|
Action |
Resource |
HTTP method |
||||
|
/Operational/ShipmentIdentifiers/ByBarcode |
POST | |||||
|
/Operational/ShipmentIdentifiers/ByOrderNumber |
POST |
|||||
|
/Operational/ShipmentIdentifiers/ByPickupCode |
POST |
|||||
|
/Operational/ShipmentIdentifiers/ByDateRange |
POST |
|||||
|
/Operational/Shipments/byBarcode |
POST |
|||||
|
/operational/shipments/byOrderNumber
|
POST |
|||||
|
/Operational/Shipments/byPickupCode |
POST |
|||||
|
/Operational/ShipmentIdentifiers/byDateRange |
POST |
|||||
|
/operational/shipments/{shipmentUuid}/documents |
POST |
|||||
|
/Operational/Shipments/{shipmentUuid} |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/summary-document |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/summary-document/{packageUuid} |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/additional-information |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/container-information |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/events/valid |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/binaries/{binaryUuid} |
GET |
|||||
|
/Operational/Shipments/{shipmentUuid}/status |
PUT |
|||||
|
/Operational/Shipments/{shipmentUuid}/packages/{packageUuid}/status |
PUT |
|||||
|
/operational/shipments/{shipmentUuid}/address |
PUT |
|||||
|
/operational/shipments/{shipmentUuid}/amounts |
PUT |
|||||
|
/operational/shipments/{shipmentUuid}/references-messages |
PUT |
|||||
|
/operational/shipments/{shipmentUuid}/anonymize |
PUT |
|||||
|
/operational/shipments/{shipmentUuid}/documents/{documentUuid} |
DELETE |
|||||
Lookup Shipments By Barcode
HTTP POST: ../Operational/ShipmentIdentifiers/ByBarcode
Will lookup shipments based on the barcode.
Request syntax
{
"query": "sampleBarcode",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
See under Parameters which are required and which are optional.
Response syntax
[
{
"uuid": "",
"number": "",
"submitDate": "",
"installation": "",
"actor": "",
"carrier": ""
},
"..."
]
Lookup Shipments By Order Number
HTTP POST: ../Operational/ShipmentIdentifiers/ByOrderNumber
Will lookup shipments based on the order number (also on additional order number).
Request syntax
{
"query": "sampleBarcode",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
See under Parameters which are required and which are optional.
Response syntax
[
{
"uuid": "", //shipment tag
"number": "", //barcode
"submitDate": "", //shipment submit date
"installation": "", //shipment installation tag
"actor": "", //shipment actor tag
"carrier": "" //shipment carrier tag
},
"..."
]
Lookup Shipments By Pickup Code
HTTP POST: ../Operational/ShipmentIdentifiers/ByPickupCode
Will return the main shipment information. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}).
Request syntax
{
"query": "samplePickupCode",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
See under Parameters which are mandatory and which are optional.
Response syntax
[
{
"uuid": "", //shipment tag
"number": "", //barcode
"submitDate": "", //shipment submit date
"installation": "", //shipment installation tag
"actor": "", //shipment actor tag
"carrier": "" //shipment carrier tag
},
"..."
]
Lookup Shipments By Date Range
HTTP POST: ../Operational/ShipmentIdentifiers/ByDateRange
Will return the main shipment information. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}). DateRangeSource must be specified: 1 - submit date, 2 - modified date. The difference between startDate and endDate should be no more than 24h.
Request syntax
{
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"dateRangeSource": 1,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
See under Parameters which are mandatory and which are optional.
Response syntax
[
{
"uuid": "", //shipment tag
"number": "", //barcode
"submitDate": "", //shipment submit date
"installation": "", //shipment installation tag
"actor": "", //shipment actor tag
"carrier": "" //shipment carrier tag
},
"..."
]
ShipmentsByBarcode
HTTP POST: ../Operational/Shipments/byBarcode
Look up shipments by barcode and return a list of the actual shipment objects
Request Syntax
{
"query": "",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"dateRangeSource": 1,
"installationTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"actorTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"carrierTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"]
}
Response Syntax
{
"uuid": "00000000-0000-0000-0000-000000000001",
"dateModified": "2021-04-21T10:14:44+00:00",
"number": "364367375745783",
"shipmentType": 0,
"shipmentTypeName": "Unknown",
"installationId": "141532564364",
"installation": "00000000-0000-0000-0000-000000000001",
"actor": "00000000-0000-0000-0000-000000000001",
"carrier": "00000000-0000-0000-0000-000000000001",
"carrierName": "ScanApp orphan",
"product": "00000000-0000-0000-0000-000000000001",
"productName": "some product",
"submitDate": "2021-04-21T11:14:44+00:00",
"isDeleted": false,
"insuranceGroup": 0,
"labelsCount": 0,
"freightBillsCount": 0,
"isAnonymized": false,
"addresses": [
{
"typeId": 2,
"typeName": "Sender",
"name1": "sender address",
"countryCode": "RO"
},
{
"typeId": 1,
"typeName": "Receiver",
"name1": "receiver address",
"countryCode": "RO"
}
],
"messages": [],
"references": [],
"services": [],
"documents": [],
"events": [],
"lines": [
{
"uuid": "35f52819-cece-4bfb-b203-8d25cc5ccc5c",
"goodsTypeId": 0,
"recycleCount": 0,
"recycleTypeId": 0,
"itemNumber": 0,
"isDeleted": false,
"references": [],
"packages": [
{
"uuid": "38d4b9aa-458b-4888-bd9e-c951b7bb6529",
"number": "3463434734",
"isDeleted": false,
"itemNumber": 0,
"references": [],
"events": [
{
"uuid": "e675237d-697c-4069-8ed6-5765abc04b35",
"originId": 3,
"configurationUuid": "3_6633",
"configurationName": "Loaded on truck",
"normalizedStatusId": 2000,
"normalizedStatusName": "In transit",
"date": "2021-04-21T10:14:44+00:00",
"weight": 0.2,
"height": 0.5,
"length": 0.5,
"width": 0.5,
"volume": 0.125,
"userName": "username",
"moneyAmounts": [],
"coordinates": {
"latitude": 45.6547687109985,
"longitude": 25.6283489708096
},
"details": [
{
"typeId": 0,
"description": "DynamicProperties",
"details": [
{
"typeId": 2,
"description": "CustomCode1",
"value": "CC1",
"details": []
},
{
"typeId": 2,
"description": "CustomCode2",
"value": "CC2",
"details": []
}
]
}
]
}
],
"documents": []
}
],
"dangerousGoods": []
}
],
"detailGroups": [],
"binaries": []
}
ShipmentsByOrderNumber
HTTP POST: ../Operational/Shipments/byOrderNumber
Look up shipments by order number and return a list of shipments.
Request syntax:
{
"query": "",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"dateRangeSource": 1,
"installationTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"actorTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"carrierTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"]
}
Response syntax:
{
"uuid": "00000000-0000-0000-0000-000000000001",
"dateModified": "2021-04-21T10:14:44+00:00",
"number": "364367375745783",
"shipmentType": 0,
"shipmentTypeName": "Unknown",
"installationId": "141532564364",
"installation": "00000000-0000-0000-0000-000000000001",
"actor": "00000000-0000-0000-0000-000000000001",
"carrier": "00000000-0000-0000-0000-000000000001",
"carrierName": "ScanApp orphan",
"product": "00000000-0000-0000-0000-000000000001",
"productName": "some product",
"submitDate": "2021-04-21T11:14:44+00:00",
"isDeleted": false,
"insuranceGroup": 0,
"labelsCount": 0,
"freightBillsCount": 0,
"isAnonymized": false,
"addresses": [
{
"typeId": 2,
"typeName": "Sender",
"name1": "sender address",
"countryCode": "RO"
},
{
"typeId": 1,
"typeName": "Receiver",
"name1": "receiver address",
"countryCode": "RO"
}
],
"messages": [],
"references": [],
"services": [],
"documents": [],
"events": [],
"lines": [
{
"uuid": "35f52819-cece-4bfb-b203-8d25cc5ccc5c",
"goodsTypeId": 0,
"recycleCount": 0,
"recycleTypeId": 0,
"itemNumber": 0,
"isDeleted": false,
"references": [],
"packages": [
{
"uuid": "38d4b9aa-458b-4888-bd9e-c951b7bb6529",
"number": "3463434734",
"isDeleted": false,
"itemNumber": 0,
"references": [],
"events": [
{
"uuid": "e675237d-697c-4069-8ed6-5765abc04b35",
"originId": 3,
"configurationUuid": "3_6633",
"configurationName": "Loaded on truck",
"normalizedStatusId": 2000,
"normalizedStatusName": "In transit",
"date": "2021-04-21T10:14:44+00:00",
"weight": 0.2,
"height": 0.5,
"length": 0.5,
"width": 0.5,
"volume": 0.125,
"userName": "username",
"moneyAmounts": [],
"coordinates": {
"latitude": 45.6547687109985,
"longitude": 25.6283489708096
},
"details": [
{
"typeId": 0,
"description": "DynamicProperties",
"details": [
{
"typeId": 2,
"description": "CustomCode1",
"value": "CC1",
"details": []
},
{
"typeId": 2,
"description": "CustomCode2",
"value": "CC2",
"details": []
}
]
}
]
}
],
"documents": []
}
],
"dangerousGoods": []
}
],
"detailGroups": [],
"binaries": []
}
ShipmentsByPickupCode
HTTP POST: ../Operational/Shipments/byPickupCode
Look up shipments by pickup code and return a list of shipments.
Request syntax
{
"query": "",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"dateRangeSource": 1,
"installationTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"actorTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"carrierTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"]
}
Response syntax
{
"uuid": "00000000-0000-0000-0000-000000000001",
"dateModified": "2021-04-21T10:14:44+00:00",
"number": "364367375745783",
"shipmentType": 0,
"shipmentTypeName": "Unknown",
"installationId": "141532564364",
"installation": "00000000-0000-0000-0000-000000000001",
"actor": "00000000-0000-0000-0000-000000000001",
"carrier": "00000000-0000-0000-0000-000000000001",
"carrierName": "ScanApp orphan",
"product": "00000000-0000-0000-0000-000000000001",
"productName": "some product",
"submitDate": "2021-04-21T11:14:44+00:00",
"isDeleted": false,
"insuranceGroup": 0,
"labelsCount": 0,
"freightBillsCount": 0,
"isAnonymized": false,
"addresses": [
{
"typeId": 2,
"typeName": "Sender",
"name1": "sender address",
"countryCode": "RO"
},
{
"typeId": 1,
"typeName": "Receiver",
"name1": "receiver address",
"countryCode": "RO"
}
],
"messages": [],
"references": [],
"services": [],
"documents": [],
"events": [],
"lines": [
{
"uuid": "35f52819-cece-4bfb-b203-8d25cc5ccc5c",
"goodsTypeId": 0,
"recycleCount": 0,
"recycleTypeId": 0,
"itemNumber": 0,
"isDeleted": false,
"references": [],
"packages": [
{
"uuid": "38d4b9aa-458b-4888-bd9e-c951b7bb6529",
"number": "3463434734",
"isDeleted": false,
"itemNumber": 0,
"references": [],
"events": [
{
"uuid": "e675237d-697c-4069-8ed6-5765abc04b35",
"originId": 3,
"configurationUuid": "3_6633",
"configurationName": "Loaded on truck",
"normalizedStatusId": 2000,
"normalizedStatusName": "In transit",
"date": "2021-04-21T10:14:44+00:00",
"weight": 0.2,
"height": 0.5,
"length": 0.5,
"width": 0.5,
"volume": 0.125,
"userName": "username",
"moneyAmounts": [],
"coordinates": {
"latitude": 45.6547687109985,
"longitude": 25.6283489708096
},
"details": [
{
"typeId": 0,
"description": "DynamicProperties",
"details": [
{
"typeId": 2,
"description": "CustomCode1",
"value": "CC1",
"details": []
},
{
"typeId": 2,
"description": "CustomCode2",
"value": "CC2",
"details": []
}
]
}
]
}
],
"documents": []
}
],
"dangerousGoods": []
}
],
"detailGroups": [],
"binaries": []
}
ShipmentsByDateRange
HTTP POST: ../Operational/Shipments/byDateRange
Look up shipments by date range and return a list of shipments.
Request syntax
{
"query": "",
"startDate": "2020-10-22T09:07:53+00",
"endDate": "2020-10-22T11:07:53+00",
"pageSize": 20,
"pageIndex": 0,
"dateRangeSource": 1,
"installationTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"actorTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"],
"carrierTags": ["452ee352-f0c9-42c7-b4c2-23994cc922ac"]
}
Response syntax
{
"uuid": "00000000-0000-0000-0000-000000000001",
"dateModified": "2021-04-21T10:14:44+00:00",
"number": "364367375745783",
"shipmentType": 0,
"shipmentTypeName": "Unknown",
"installationId": "141532564364",
"installation": "00000000-0000-0000-0000-000000000001",
"actor": "00000000-0000-0000-0000-000000000001",
"carrier": "00000000-0000-0000-0000-000000000001",
"carrierName": "ScanApp orphan",
"product": "00000000-0000-0000-0000-000000000001",
"productName": "some product",
"submitDate": "2021-04-21T11:14:44+00:00",
"isDeleted": false,
"insuranceGroup": 0,
"labelsCount": 0,
"freightBillsCount": 0,
"isAnonymized": false,
"addresses": [
{
"typeId": 2,
"typeName": "Sender",
"name1": "sender address",
"countryCode": "RO"
},
{
"typeId": 1,
"typeName": "Receiver",
"name1": "receiver address",
"countryCode": "RO"
}
],
"messages": [],
"references": [],
"services": [],
"documents": [],
"events": [],
"lines": [
{
"uuid": "35f52819-cece-4bfb-b203-8d25cc5ccc5c",
"goodsTypeId": 0,
"recycleCount": 0,
"recycleTypeId": 0,
"itemNumber": 0,
"isDeleted": false,
"references": [],
"packages": [
{
"uuid": "38d4b9aa-458b-4888-bd9e-c951b7bb6529",
"number": "3463434734",
"isDeleted": false,
"itemNumber": 0,
"references": [],
"events": [
{
"uuid": "e675237d-697c-4069-8ed6-5765abc04b35",
"originId": 3,
"configurationUuid": "3_6633",
"configurationName": "Loaded on truck",
"normalizedStatusId": 2000,
"normalizedStatusName": "In transit",
"date": "2021-04-21T10:14:44+00:00",
"weight": 0.2,
"height": 0.5,
"length": 0.5,
"width": 0.5,
"volume": 0.125,
"userName": "username",
"moneyAmounts": [],
"coordinates": {
"latitude": 45.6547687109985,
"longitude": 25.6283489708096
},
"details": [
{
"typeId": 0,
"description": "DynamicProperties",
"details": [
{
"typeId": 2,
"description": "CustomCode1",
"value": "CC1",
"details": []
},
{
"typeId": 2,
"description": "CustomCode2",
"value": "CC2",
"details": []
}
]
}
]
}
],
"documents": []
}
],
"dangerousGoods": []
}
],
"detailGroups": [],
"binaries": []
}
Add Document to Shipment
HTTP GET: ../operational/shipments/{shipmentUuid}/documents
Add one or more documents to a shipment
Request syntax
A HTTP form object containing the list of documents to be added to the shipment.
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Each file uploaded has a maximum size of 24 mb.
Get Shipment
HTTP GET: ../Operational/Shipments/{shipmentUuid}
Will return the main shipment information. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}).
The shipment information returned is filtered according to the Shipment Viewer profile assigned to the user making the request. If the user does not have an SV profile defined, a default profile will be used, which will only show a basic collection of fields. The SV profile can be created and modified by the owner/admin. An example of data filtering through the use of a profile is choosing which addresses and address fields to display in the Shipment Viewer, or showing/hiding additional shipment information. Read more about using the Shipment Viewer profile to manage data in the response here.
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0
Response syntax
If the action is successful, the service sends back an HTTP 200 response with an json object containing the shipment information.
Get Shipment Summary Document
HTTP GET: ../Operational/Shipments/{shipmentUuid}/summary-document
Will return the proof of delivery for the shipment, as a PDF file.
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/summary-document
Response syntax
If the action is successful, the service sends back an HTTP 200 response with pdf file containing the proof of delivery document.
Get Package Summary Document
HTTP GET: ../Operational/Shipments/{shipmentUuid}/summary-document/{packageUuid}
Will return the proof of delivery for the package, as a PDF file.
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/summary-document/00000000-fa25-4b52-bc16-760fbe7207b1
Response syntax
If the action is successful, the service sends back an HTTP 200 response with pdf file containing the proof of delivery document.
Get Shipment Additional Information
HTTP GET: ../Operational/Shipments/{shipmentUuid}/additional-information
Will return the additional shipment information, such as tracking URLs, latest status and ETA. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}).
The shipment submit date is required.
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/additional-information?date=2020-10-30T10:41:12.00
Response syntax
{
"trackingUrls": [
{
"text": "104770186377",
"url": "https://www.test.test.com?test=test&shipment=urltestKind147TrackingUrl"
},...
{
"text": "104770186377",
"url": "https://www.test.test.com?test=test&returnDataDynamicProperty=urltestPublic"
},
{
"text": "00370730250478724870",
"url": "https://www.test.test.com?test=test&returnDataDynamicProperty=urltestPublic"
}
],
"insuranceClaimUrl": "",
"latestStatuses": [
{
"shipmentUuid": "f233a5fc-20f7-45e7-b108-827308ba04bf",
"measurements": {
"length": 0.161,
"width": 0.162,
"height": 0.163,
"weight": 0.16,
"volume": 0.000000164
},
"status": {
"normalizedStatusId": 3002,
"configurationUuid": "6_100397",
"date": "2021-04-27T14:07:00.1536644+02:00"
}
},....
{
"shipmentUuid": "f233a5fc-20f7-45e7-b108-827308ba04bf",
"packageUuid": "628a1aa2-c988-4032-a67d-32f90820959e",
"status": {
"normalizedStatusId": 3002,
"configurationUuid": "6_100397",
"date": "2021-04-27T14:07:00.1536644+02:00"
}
},
{
"shipmentUuid": "f233a5fc-20f7-45e7-b108-827308ba04bf",
"packageUuid": "aebdc68c-13c6-4b8b-8d81-da06dcd0734b",
"measurements": {
"length": 0.161,
"width": 0.162,
"height": 0.163,
"weight": 0.16,
"volume": 0.000000164
},
"status": {
"normalizedStatusId": 3002,
"configurationUuid": "6_100397",
"date": "2021-04-27T14:07:00.1536644+02:00"
}
},
{
"shipmentUuid": "f233a5fc-20f7-45e7-b108-827308ba04bf",
"packageUuid": "c6411937-4d9b-4414-af1d-00a642a1ce4b",
"status": {
"normalizedStatusId": 3002,
"configurationUuid": "6_100397",
"date": "2021-04-27T14:07:00.1536644+02:00"
}
}
]
}
See an overview of normalized status names and IDs here.
Get Shipment Container Information
HTTP GET: ../Operational/Shipments/{shipmentUuid}/container-information
Will return the container information for a shipment. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}).
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/container-information
Response syntax
[
{
"containerUuid": "98e8bb84-2c43-46f4-b3e6-6a6a30bcca97",
"containerLabel": "Aalesund East",
"submitDate": "0001-01-01T00:00:00+00:00"
}
]
Get Shipment Valid Events
HTTP GET: ../Operational/Shipments/{shipmentUuid}/events/valid
Will return the list of valid events that can be used to send as new shipment status. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}).
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/events/valid
Response syntax
[
{
"uuid": "6_5006",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Shipment delivered",
"code": "Pakke levert_2082",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
},
{
"uuid": "6_5025",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Picked up at customer",
"code": "Hentet hos kunde_2101",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
},
{
"uuid": "6_8172",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Delivered at customer",
"code": "Delivered at customer_5248",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
},
{
"uuid": "6_100661",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Loaded to truck",
"code": "Tru4545",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
},
{
"uuid": "6_100662",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Receiver not at home",
"code": "Ex65",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
},
{
"uuid": "6_100793",
"dateModified": "0001-01-01T00:00:00+00:00",
"name": "Carrier Exception",
"code": "car11",
"normalizedStatusUuid": 0,
"isDeleted": false,
"isPublic": false
}
]
See an overview of normalized status names and IDs here.
Get Shipment Document
HTTP GET: ../Operational/Shipments/{shipmentUuid}/binaries/{binaryUuid}
Will return a document attached to the shipment. Shipment, and document unique identifiers, will be provided in the URI ({shipmentUuid}, {binaryUuid}).
Request syntax
GET /operational/shipments/ba77a9bc-fa25-4b52-bc16-760fbe7207b0/binaries/00000000-fa25-4b52-bc16-760fbe7207b1
Response syntax
If successful, the method will return an HTTP 200 response, with a file attachment.
Send Shipment Status
HTTP PUT: ../Operational/Shipments/{shipmentUuid}/status
Will send new status for a shipment. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}). The date from the request must respect the ISO-8601 format (see ISO 8601 - Wikipedia).
Request syntax
{
"EventType": "6_42",
"Comments": "new status",
"Date": "2020-09-02T17:38:40+02:00",
"StorageLocation": "Location A"
}
Response syntax
If successful, the method will simply return an empty response of type HTTP 202 (Accepted).
Send Package Status
HTTP PUT: ../Operational/Shipments/{shipmentUuid}/packages/{packageUuid}/status
Will send new status for a shipment package. Shipment unique identifier (tag) will be provided in the URI ({shipmentUuid}). Package unique identifier (tag) will be provided in the URI (packageUuid). The date from the request must in a UTC date ( see Standard date and time format strings | Microsoft Docs for more information), otherwise an error message will be returned, stating “Only UTC kind accepted for date!”.
Request Syntax
{
"EventType": "6_42",
"Comments": "new status",
"Date": "2020-09-02T17:38:22+02:00",
"StorageLocation": "Location B"
}
Response syntax
If successful, the method will simply return an empty response of type HTTP 202 (Accepted).
Send Shipment Address update
HTTP PUT: ../Operational/shipments/{shipmentUuid}/address
Will update the address fields for a shipment address.
Request syntax
{
"name1": "string",
"name2": "string",
"street1": "string",
"street2": "string",
"countryCode": "string",
"state": "string",
"region": "string",
"county": "string",
"district": "string",
"city": "string",
"erpRef": "string",
"email": "string",
"phone": "string",
"mobile": "string",
"poPostCode": "string",
"poCity": "string",
"postCode": "string",
"poBox": "string",
"attention": "string",
"fax": "string",
"openingHours": "string",
"receiverRef": "string",
"province": "string",
"vatNo": "string",
"voecNumber": "string",
"typeId": 0
}
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Send Shipments Amounts update
HTTP PUT: ../Operational/shipments/{shipmentUuid}/amounts
Will update some of the amount fields for a shipment (Price 1, Price 2, fixed price, carrier price).
Request syntax
{
"price1": 0,
"price1CurrencyCode": "string",
"price2": 0,
"price2CurrencyCode": "string",
"fixedPrice": 0,
"fixedPriceCurrencyCode": "string",
"carrierPrice": 0,
"carrierPriceCurrencyCode": "string"
}
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Send Shipment Reference Update
HTTP PUT: ../Operational/shipments/{shipmentUuid}/references-messages
Will update a select list of references and messages for a shipment.
Request syntax
{
"orderNumber": "string",
"additionalReference": "string",
"receiverReference": "string",
"project": "string",
"carrierMessage": "string",
"driverMessage": "string",
"receiverMessage": "string"
}
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Anonymize shipment
HTTP PUT: ../Operational/shipments/{shipmentUuid}/anonymize
Will anonymize the shipment
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Delete document from shipment
HTTP PUT: ../Operational/shipments/{shipmentUuid}/anonymize
Deletes a document from a shipment.
Response syntax
If successful, the operation will return an empty response body with the HTTP status 202 - Accepted.
Using the Shipment Viewer Profile to manage data in the response
The Shipment data you get back in a response from the Shipment Data API is determined by the shipment viewer profile that is assigned to the user making the request. If the user does not have a shipment viewer profile defined, a default profile showing a basic collection of fields will be used.
A shipment viewer profile can be created and modified by the Owner or an Admin user. The fields that are enabled on a shipment viewer profile will also be enabled in the response from the Shipment Data API.
Creating a Shipment Viewer Profile:
- Log into Portal with your Owner or Admin user.
- Click on your user name and choose Settings in the menu.
- Go to Customizations > Shipment Viewer Profile and click Create new > Authenticated.
- Name your profile. Choose a name that will help you identify the profile later. The profile is enabled as default, but it can be disabled if needed.
- Set the toggle buttons to ON or OFF to manage which data should be included in the Shipment Data API response.
- Click the arrow in the Collection column to expand a collection and select or remove items by selecting or deselecting the check boxes.
- Click the Save button when you are finished with the configuration.
- To assign the new profile to a specific user, go to User Accounts > Customer Users.
- Click on the user you want to update and select the correct Shipment viewer profile. In this example we have created a profile to use for the Shipment Data API and named it accordingly.
- Click Save.
Read more in this article about creating shipment viewer profiles:
Creating Shipment Viewer Profiles and public tracking URLs
List of normalized status names and IDs
In Transit
2000 - In Transit
2001 - Out for delivery
2002 - Ready for pickup
2003 - Arrived at terminal/hub
2004 - Collected by carrier
2005 - Customs Clearance
2008 - Departed from terminal/hub
Delivered
3000 - Delivered
3001 - Partially delivered
3002 - Carded
3003 - Delivered to neighbor
Information
4000 - Other status
4001 - Update ETA
4002 - Change of address
4003 - Notification(s)/Advise
4004 - Booking information confirmed
4005 - Measurement/Price Update
Carrier exception
5000 - Carrier Exception
5001 - Other incident
5002 - Delayed
5003 - Damaged
5004 - Change to delivery
5005 - Misrouted
5006 - Failed delivery attempt
5007 - Return to sender
5008 - Lost
5009 - Force majeure
Receiver Exception
6000 - Other incident.
6001 - Return to sender
6002 - Customer refused
6003 - No property access
6004 - Delivery cancelled
6005 - Carded
Sender Exception
7000 - Other incident
7001 - Delivery cancelled
7002 - Return to sender
7003 - Insufficient address
7004 - Missing booking info
PostMan Collection
Download the Postman collection here.