Environments | {{URL}}

New baseurl: https://api.nshiftportal.com/track/shipmentdata

The new baseurl works with client IDs created in nShift Portal. 

Old baseurl: https://customer-api.consignorportal.com/ApiGateway/ShipmentData

The old baseurl works with client IDs created in Consignor Portal.

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 supports Bearer Authentication
See this article on how to generate the ClientId and ClientSecret

Example of how to request a token

curl -X POST "https://account.nshiftportal.com/idp/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_portal_shipment_data"
}

The Token is valid for 60 minutes before it expires and you have to re-authenticate

Note: If you get the following error, check where your credentials were made. If you have credentials from www.consignorportal.com you need to create new ones on www.nshiftportal.com 

All requests must 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 of how to get the data of a shipment using barcode

curl -X POST "https://api.nshiftportal.com/track/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\": []
}"

Swagger

Please refer to https://api.nshiftportal.com/track/swagger/index.html 

API Index

-

Find | Get Shipment By Barcode

Lookup shipments based on the barcode.

Request

POST {{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

POST {{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

POST {{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

POST {{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 3 - last event date
  

-

Locate Uuid | Get Shipment By Barcode

Lookup shipments Uuid based on the barcode.

Request

POST {{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

POST {{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

POST {{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

POST {{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": [],
   "dateRangeSource": 1
}

• 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.
  
• dateRangeSource [int] -
  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 a list of valid ids
• Comments - the text on the event status
• Date - the date of the event status 
• StorageLocation - an 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 a list of valid ids.
• Comments- the text on the event status
• Date - the date of the event status 
• StorageLocation- an optimal value for storage, used together with ScanApp

-

Update | Update the Receiver 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

DEL {{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