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

-

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