Using the ShipmentData API – nShift

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.

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.

Using the Consignor API requires the use of tokens (Client IDs and Client Secrets). The authorization and authentication is compliant with OAuth2 and all the methods of the public API will have 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

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

This could a barcode, a pickup code or an order number that we are searching for - either the whole item, or part of it.

Type: string

MinLength: 3

MaxLength: 36

Required: Yes

startDate

The start of the date range interval by which we search for shipments - by default it will the current date and time minus 31 days.

Type: DateTimeOffset

Min: CurrentDate minus 365 days

MaxValue: EndDate

Required: Yes

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

Min: CurrentDate minus 334 days

Max: N/A

Required: Yes

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	GET	POST	PUT	PATCH	DELETE
Lookup Shipments By Barcode	/Operational/ShipmentIdentifiers/ByBarcode	NO	YES	NO	NO	NO
Lookup Shipments By Order Number	/Operational/ShipmentIdentifiers/ByOrderNumber	NO	YES	NO	NO	NO
Lookup Shipments By Pickup Code	/Operational/ShipmentIdentifiers/ByPickupCode	NO	YES	NO	NO	NO
Lookup Shipments By Date Range	/Operational/ShipmentIdentifiers/ByDateRange	NO	YES	NO	NO	NO
Get Shipment	/Operational/Shipments/{shipmentUuid}	YES	NO	NO	NO	NO
Get Shipment Summary Document	/Operational/Shipments/{shipmentUuid}/summary-document	YES	NO	NO	NO	NO
Get Package Summary Document	/Operational/Shipments/{shipmentUuid}/summary-document/{packageUuid}	YES	NO	NO	NO	NO
Get Shipment Additional Information	/Operational/Shipments/{shipmentUuid}/additional-information	YES	NO	NO	NO	NO
Get Shipment Container Information	/Operational/Shipments/{shipmentUuid}/container-information	YES	NO	NO	NO	NO
Get Shipment Valid Events	/Operational/Shipments/{shipmentUuid}/events/valid	YES	NO	NO	NO	NO
Get Shipment Document	/Operational/Shipments/{shipmentUuid}/binaries/{binaryUuid}	YES	NO	NO	NO	NO
Send Shipment Status	/Operational/Shipments/{shipmentUuid}/status	NO	NO	YES	NO	NO
Send Package Status	/Operational/Shipments/{shipmentUuid}/packages/{packageUuid}/status	NO	NO	YES	NO	NO

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
   },
   "..."
]

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"
}

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"
}

Response syntax

If successful, the method will simply return an empty response of type HTTP 202 (Accepted).

Using the Shipment Viewer Profile to mange 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 Consignor 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.

ShipmentDataApi_collection.json
20 KB Download

nShift DeliveryHub Help

Authentication and HTTP responses

Parameters

Methods

Lookup Shipments By Barcode

Lookup Shipments By Order Number

Lookup Shipments By Pickup Code

Lookup Shipments By Date Range

Get Shipment

Get Shipment Summary Document

Get Package Summary Document

Get Shipment Additional Information

Get Shipment Container Information

Get Shipment Valid Events

Get Shipment Document

Send Shipment Status

Send Package Status

Using the Shipment Viewer Profile to mange data in the response

Creating a Shipment Viewer Profile:

List of normalized status names and IDs

PostMan Collection

Related articles