Environments | {{URL}}
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.
Authentication | Bearer
The API support Bearer Authentication
See this article on how to generate the ClientId and ClientSecret
Example on how to request a token
curl -X POST "https://www.consignorportal.com/idsrv/connect/token"
--header "Content-Type: application/x-www-form-urlencoded"
--data-urlencode "grant_type=client_credentials"
--data-urlencode "client_id={{CLIENT_ID}}"
--data-urlencode "client_secret={{CLIENT_SECRET}}"
Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI3QjA1ODk4Nzc1OEUwMkMI1NiIsInR2...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "public_api_shipmentserver"
}
The Token is valid for 60 minuts before it expires and you have to re-authenticate
All request has to have the token in the Authorization header
curl -X POST "{{URL}}/ShipServer/ApiGateway/ShipmentData/"
-H "Authorization: bearer {{TOKEN}}"
-H "Content-Type: application/json"
--data-raw "{}"
Example on how to get the data of a shipment using barcode
curl -X POST "https://customer-api.consignorportal.com/ApiGateway/ShipmentData/Operational/Shipments/ByBarcode" -H "Authorization: bearer {{TOKEN}}"
-H "Content-Type: application/json"
--data-raw "{ \"query\": \"70730254433219997\", \"startDate\": \"2023-01-12T15:13:12+01:00\", \"endDate\": \"2023-01-26T15:13:12+01:00\", \"pageSize\": 20, \"pageIndex\": 0, \"installationTags\": [], \"actorTags\": [], \"carrierTags\": [] }"
Postman Collection
This collection contains request & response examples for all requests:
https://documenter.getpostman.com/view/22736309/2s8YzL4Rrw
In order to use these requests against your own configuration/actor you need to:
How to configure and use the Postman collection
- Generate a CLIENT_ID & CLIENT_SECRET using this article:
https://helpcenter.nshift.com/hc/en-us/articles/360026218413 - Select the Environment DeliveryHUB API from the top right corner in Postman
- Update the Initial & Current value on the variables in the selected environment:
CLIENT_ID, CLIENT_SECRET - Remember to Save the Environment
- Open the Authorization folder
- Run the Authenticate request
- Update any of the request and click Send
API Index
POST | Get Shipment By Barcode | ../Shipments/ByBarcode |
POST | Get Shipment By OrderNumber | ../Shipments/ByOrderNumber |
POST | Get Shipment By PickupCode | ../Shipments/ByPickupCode |
POST | Get Shipments By Data Range | ../Shipments/ByDateRange |
POST | Get Shipment Uuid By Barcode | ../ShipmentIdentifiers/ByBarcode |
POST | Get Shipment Uuid By OrderNumber | ../ShipmentIdentifiers/ByOrderNumber |
POST | Get Shipment Uuid By PickupCode | ../ShipmentIdentifiers/ByPickupCode |
POST | Get Shipments Uuid By Data Range | ../ShipmentIdentifiers/ByDateRange |
GET | Get Shipment Information | ../:shipmentUuid |
GET | Get Shipment Additional Information | ../:shipmentUuid/additional-information |
GET | Get Shipment Container Information |
../:shipmentUuid/container-information |
GET | Get Shipment Document | ../:shipmentUuid/binaries/:binaryUuid |
GET | Get Shipment Summary Document | ../:shipmentUuid/summary-document |
GET | Get Package Summary Document | ../:shipmentUuid/summary-document/:packageUuid |
GET | Get Events | ../:shipmentUuid/events/valid |
POST | Add Documents | ../:shipmentUuid/documents |
PUT | Add Shipment Event | ../:shipmentUuid/status |
PUT | Add Package Event | ../:shipmentUuid/packages/:packageUuid/status |
PUT | Update the Receriver Address | ../:shipmentUuid/address |
PUT | Update the Amounts | ../:shipmentUuid/amounts |
PUT | Update the References | ../:shipmentUuid/references-messages |
PUT | Anonymize shipment | ../:shipmentUuid/anonymize |
DEL | Delete a document from a shipment | ../:shipmentUuid/documents/:documentUuid |
-
Find | Get Shipment By Barcode
Lookup shipments based on the barcode.
Request
GET {{URL}}/Operational/Shipments/ByBarcode
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "{{SHIPMENTNUMBER}}",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the barcode to search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Find | Get Shipment By OrderNumber
Lookup shipments based on the order number or additional order number
Request
GET {{URL}}/Operational/Shipments/ByOrderNumber
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "Order Number",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the order number to search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Find | Get Shipment By PickupCode
Lookup shipments based on the PickupCode.
Request
GET {{URL}}/Operational/Shipments/ByPickupCode
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "ScanApp Pickup Code",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the ScanApp Pickup Codeto search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Find | Get Shipments By Data Range
Lookup shipments based on a Date Range.
Request
GET {{URL}}/Operational/Shipments/ByDateRange
Request body
The request body has to be application/json and the payload uses the following keys
{
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
-
startDate: ISODate -
max 24 hours between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00. - endDate: ISODate - max 24 hours between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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. -
dataRangeSource -
Determines the date field to query by in case of a data range lookup
Values can be: 1 - submit date 2 - date modified
-
Locate Uuid | Get Shipment By Barcode
Lookup shipments Uuid based on the barcode.
Request
GET {{URL}}/Operational/ShipmentIdentifiers/ByBarcode
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "{{SHIPMENTNUMBER}}",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the barcode to search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Locate Uuid | Get Shipment By OrderNumber
Lookup shipments Uuid based on the order number or additional order number
Request
GET {{URL}}/Operational/ShipmentIdentifiers/ByOrderNumber
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "Order Number",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the order number to search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Locate Uuid | Get Shipment By PickupCode
Lookup shipments Uuid based on the PickupCode.
Request
GET {{URL}}/Operational/ShipmentIdentifiers/ByPickupCode
Request body
The request body has to be application/json and the payload uses the following keys
{
"query": "ScanApp Pickup Code",
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
- query: string - the ScanApp Pickup Codeto search for
-
startDate: ISODate -
max 31 days between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00 - endDate: ISODate - max 31 days between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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.
-
Locate Uuid | Get Shipments By Data Range
Lookup shipments Uuid based on a Date Range.
Request
GET {{URL}}/Operational/ShipmentIdentifiers/ByDateRange
Request body
The request body has to be application/json and the payload uses the following keys
{
"startDate": "{{today-14days}}",
"endDate": "{{today}}",
"pageSize": 20,
"pageIndex": 0,
"installationTags": [],
"actorTags": [],
"carrierTags": []
}
-
startDate: ISODate -
max 24 hours between start and end date
No more than 365 days old
If no offset is provided it is automatically set to 00. - endDate: ISODate - max 24 hours between start and end date
- pageSize: int - The number of items to retrieve in one batch - default is 20.
- pageIndex: int - Zero-based results batch index.
- installationTags: [string] - Collection of installation identifiers to be applied on search.
- actorTags: [string] -
Collection of actor identifiers to be applied on search.
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: [string] -
Collection of carrier identifiers to be applied on search.
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. -
dataRangeSource -
Determines the date field to query by in case of a data range lookup
Values can be: 1 - submit date 2 - date modified
-
Information | Get Shipment Information
Return the main shipment information
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Information | Get Shipment Additional Information
R eturn the additional shipment information, such as tracking URLs, the latest status, and ETA.
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/additional-information
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Information | Get Shipment Container Information
Return the container information for a shipment.
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/container-information
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Information | Get Shipment Document
Return a document attached to the shipment
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/binaries/:binaryUuid
- shipmentUuid: string - unique identifier for identifying a Shipment.
- binaryUuid: string - unique identifier for identifying a document attached to a shipment.
-
Information | Get Shipment Summary Document
Return the proof of delivery for the shipment, as a PDF file.
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/summary-document
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Information | Get Package Summary Document
Return the proof of delivery for the package, as a PDF file.
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/summary-document/:packageUuid
- shipmentUuid: string - unique identifier for identifying a Shipment.
- packageUuid: string - unique identifier for identifying a package.
-
Update | Get Events
Return the list of valid events that can be used to send as new shipment status
Request
GET {{URL}}/Operational/Shipments/:shipmentUuid/events/valid
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Update | Add Documents
Add one or more documents to a shipment
Request
POST {{URL}}/Operational/Shipments/:shipmentUuid/documents
- shipmentUuid: string - unique identifier for identifying a Shipment.
Request body
The request body has to be application/form-data and the payload uses the following keys
{
"file0": "base64",
"file1": "base64"
}
- file0: base64 - Each file uploaded has a maximum size of 24 mb.
-
Update | Add Shipment Event
Update a shipment with a new status event
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/status
- shipmentUuid: string - unique identifier for identifying a Shipment.
Request body
The request body has to be application/json and the payload uses the following keys
{
"EventType": "6_11565",
"Comments": "it's now delivered using postman",
"Date": "{{today}}",
"StorageLocation": "Location A"
}
- EventType - use the method Get Events to see valid a list of valid ids
- Comments - the text on the event status
- Date - the date of the event status
- StorageLocation - a optimal value for storage, used together with ScanApp
-
Update | Add Package Event
Update a package with a new status event
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/packages/:packageUuid/status
- shipmentUuid: string - unique identifier for identifying a Shipment.
- packageUuid: string - unique identifier for identifying a package.
Request body
The request body has to be application/json and the payload uses the following keys
{
"EventType": "6_11565",
"Comments": "it's now delivered using postman",
"Date": "{{today}}",
"StorageLocation": "Location A"
}
- EventType- use the method Get Events to see valid a list of valid ids
- Comments- the text on the event status
- Date - the date of the event status
- StorageLocation- a optimal value for storage, used together with ScanApp
-
Update | Update the Receriver Address
Update the address fields on a shipment.
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/address
- shipmentUuid: string - unique identifier for identifying a Shipment.
Request body
The request body has to be application/json and the payload uses the following object
{
"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
}
-
Update | Update the Amounts
Update the Amounts
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/amounts
- shipmentUuid: string - unique identifier for identifying a Shipment.
Request body
The request body has to be application/json and the payload uses the following object
{
"price1": 0,
"price1CurrencyCode": "string",
"price2": 0,
"price2CurrencyCode": "string",
"fixedPrice": 0,
"fixedPriceCurrencyCode": "string",
"carrierPrice": 0,
"carrierPriceCurrencyCode": "string"
}
-
Update | Update the References
Update the References
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/references-messages
- shipmentUuid: string - unique identifier for identifying a Shipment.
Request body
The request body has to be application/json and the payload uses the following object
{
"orderNumber": "string",
"additionalReference": "string",
"receiverReference": "string",
"project": "string",
"carrierMessage": "string",
"driverMessage": "string",
"receiverMessage": "string"
}
-
Update | Anonymize the shipment
Anonymize the shipment
Request
PUT {{URL}}/Operational/Shipments/:shipmentUuid/anonymize
- shipmentUuid: string - unique identifier for identifying a Shipment.
-
Update | Delete a document from a shipment
Delete a document from a shipment
Request
DELETE {{URL}}/Operational/Shipments/:shipmentUuid/documents/:documentUuid
- shipmentUuid: string - unique identifier for identifying a Shipment.
- documentUuid: string - unique identifier for identifying a Document.
HTTP status codes:
200 OK - Data successfully received and is sent for processing
401 Unauthorized - Not valid credentials
400 Bad Request - Invalid input data
500 InternalServerError - Unknown error
429 Too many requests - Exceeded the limit of calls per minute. The limit is set according to the customer's subscription.
Normalized status names
System
1000 - Created
1001 - Transmit
1002 - Deleted
1003 - Internal
1004 - Customer advised
1005 - Undelete
1007 - Onboarded to container
1008 - Offboarded from container
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 canceled
6005 - Carded
Sender Exception
7000 - Other incident
7001 - Delivery canceled
7002 - Return to sender
7003 - Insufficient address
7004 - Missing booking info