This article will explain how to use the Container API to create and manage containers. It will explain the possible parameters and list the different methods used.

Go to:

• Authentication and HTTP responses
• Parameters
• Methods

  

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. 

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.

Endpoint

https://customer-api.consignorportal.com/ApiGateway/Containers/Containers

(The endpoint can only be used for sending requests and not 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

ParentIdentifier

This is the identifier of the “parent” container. This could be a barcode on a shipment or package, or this could be related to a virtual container. If this is a virtual container it would reference either an ID or a string (example could be to reference a “delivery route” --> London east).

Type: string

MinLength: 2

MaxLength: 50

Required: Yes

 

IsVirtualParent

If this option is set to true it means that the property “ParentIdentifier” refers to a virtual entity and is not linked to a physical shipment or package. The string used for input will be reused in case you reference the same string again.

Type: bool

Required: No

Default: false

 

ActionCenterUuid

This refers to the unique identifier of ActionCenter. Provide this identifier if you intend to use Scan App. ActionCenterUuid will be associated with all container definitions and to the template in case of a virtual container.

Type: string

Required: No

 

ChildrenIdentifier

This refers to the list of items that will be added to the parent container. This refers to the barcodes used on shipments or packages. The maximum number of items in this list is set to 50. If you need to add more items to a container use the separate action 2.2  "Add Children to Container".

Type: List<string>

Min item length: 2

Max item length: 50

Required: yes

Maximum count: 50

 

DateCreated

Local Iso8601datetime with offset. Example of correct format: "2022-07-01T17:55:13+02:00". Please note that we only support the extended notations, not the basic notations without hyphens.

Type: DateTimeOffset

Required: Yes

 

MaxDaysOld

The maximum days of validity of ParentIdentifier if referenced against shipment or packages. This is not used for virtual containers. The default number of days will be set to 10 days.

Type: int

Required: no

Default: 10

Maximum value: 90

 

EventCode

If you would like to add an event along with the container you can input an EventCode. This will then be populated on all children in the given container.

Type: string

Required: No

   

Methods

Actions available

Action	Resource	GET	POST	PUT	PATCH	DELETE
Create Container	/Containers/	N/A	YES	N/A	N/A	N/A
Add children to container	/Containers/{Uuid}/	N/A	N/A	YES	N/A	N/A
Close container	/Containers/{Uuid}/Close/	N/A	YES	N/A	N/A	N/A
Add event to container	/Containers/{Uuid}/Events/	N/A	YES	N/A	N/A	N/A
Get container children count	/Containers/{Uuid}/Children/Count/	YES	N/A	N/A	N/A	N/A
Get container children	/Containers/{Uuid}/Children/	YES	N/A	N/A	N/A	N/A
Get active parent of active child	/Containers/children/{identifier}	YES	N/A	N/A	N/A	N/A
Get active containers	/Containers/Active?identifier={ identifier}&pageSize={pageSize}&pageIndex={pageIndex}	YES	N/A	N/A	N/A	N/A
Get container by identifier or uuid	/Containers/{Uuid}/Lock/	YES	N/A	N/A	N/A	N/A
Lock container	/Containers/{Uuid}/Lock/	N/A	YES	N/A	N/A	N/A
Unlock container	/Containers/{Uuid}/Lock/	N/A	YES	N/A	N/A	N/A
Container load status	/Containers/{Uuid}/load/status	YES	N/A	N/A	N/A	N/A
Container load items	/Containers/{Uuid}/load/items?confirmed={confirmStatus}&pageSize={pageSize}&pageIndex={pageIndex}	YES	N/A	N/A	N/A	N/A
Confirm parent	/Containers/{uuid}/confirm/parent	N/A	YES	N/A	N/A	N/A
Get owner settings	/Settings	YES	N/A	N/A	N/A	N/A
Add or update owner settings	/Settings	N/A	N/A	YES	N/A	N/A
Get active containers count	/Containers/Active/Count	N/A	YES	N/A	N/A	N/A

  

Create container

HTTP POST: /../Containers/

Will create the container and return the unique identifiers needed. Starting with version 4.1.0.0 of the API, if ParentUuid is returned, the operation was processed with success (is now done synchronously towards the storage) and you can proceed with the next operations if needed (example: “AddChildren”).

Request syntax

{ 
   "ParentIdentifier":string,
   "ChildrenIdentifier" : [string],
   "DateCreated" : datetime,
   "IsVirtualParent" : bool,
   "MaxDaysOld" : int,
   "EventCode" :string 
}

Response syntax

{ 
 "ParentUuid":string
}

Request example:

{ 
   "ParentIdentifier":"4015468532135485",
   "ChildrenIdentifier" : [{"4015468532198642"},{"4015468532142516"}]
   "DateCreated" : "2022-07-01T17:55:13+02:00",
   "IsVirtualParent " : false,
   "MaxDaysOld" : 15
   "EventCode" : "B542"
}

Response example

{ "911BD835-DBAE-4881-9590-5F00E5812060" }

 

 

Add children to container

HTTP PUT: /../Containers/{uuid}

Use this call in order to add one or more children to an existing container. If EventCode is provided, this will propagate the event to any children attached to the container.

Container unique identifier will be provided in the URI {uuid}.

Request syntax

  {
   "ChildrenIdentifier" : [string],
   "DateCreated" : datetime,
   "MaxDaysOld" : int,
   "EventCode" : string
  } 

Response syntax

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Request example:  ParentUuid will be provided in URL.

  { 
   "ChildrenIdentifier" : [
     {
       "40100000000000000004"
     },
     {
       "40100000000000000005"
     }, 
     {
       "40100000000000000006"
     }
   ],
 "DateCreated" : "2022-07-01T17:55:13+02:00",
 "IsVirtualParent" : false,
 "EventCode" : "A5458"
 }

Response example:

HTTP 200 OK

Maximum count: 50

 

  

Close container

HTTP POST: /../Containers/{uuid}/Close

Use this method in order to close and update the relationship for all the connected children. Once the tree is closed, no more children can be added to the container.

Container unique identifier will be provided in the URI {uuid}.

Request syntax

ParentUuid from URI

Response syntax

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Request example:

ParentUuid will be provided in the URL.

Response example:

HTTP 200 OK

 

 

Send event to container 

HTTP POST: /../Containers/{uuid}/Event

Use this method to send an event to a container and its linked children. The event will be propagated to all-level children. In case of a closing event (defined on the event), the status of the container will be set to "Closed" (since all children would be considered closed, the container will also be automatically closed). ParentUuid will be provided in the URL. EventCode is mandatory.

Container unique identifier will be provided in the URI {uuid}.

Request syntax

{
  "EventCode" : string,
  "DateCreated" : datetime
}

Response syntax

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Request example:

ParentUuid will be provided in URL.

  { 
   "EventCode" : "B5469",
   "DateCreated" : "2022-07-01T17:55:13+02:00"
  }

Response example:

HTTP 200 OK

 

 

Get container children count

HTTP GET: /../Containers/{uuid}/Count

Use this method to get the count of the total number of level 1 children (as the container might contain other virtual containers with its own children, the total count could be higher if you count all levels)

Container unique identifier will be provided in the URI {uuid}.

Request syntax

ParentUuid from URI

Response syntax

intValue

Request example:

  GET  …./ /Containers/911BD835-DBAE-4881-9590-5F00E5812060/Count

Response example:

5

 

 

Get container children 

HTTP GET: /../Containers/{uuid}/Children

Use this method to get the list of level 1 children. HasChildren will be set to true in case they have children, otherwise, it will be set to false.

Container unique identifier will be provided in the URI {uuid}.

Request syntax

ParentUuid from URI

Response syntax

  {
    [
      {
        "ChildUuid": string,
        "ChildIdentifier": string, 
        "HasChildren" : bool
      }
    ]
  }

Request example:

  GET  …./ /Containers/911BD835-DBAE-4881-9590-5F00E5812060/Children

Response example:

 { 
   [
    {
      "ChildUuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
      "ChildIdentifier": "Child1Identifier",
      "HasChildren" : true
    },
    {
      "ChildUuid": "BEDFBB40-C1BA-4900-94D3-80C5C24CFF06",
      "ChildIdentifier": "Child2Identifier" ,
      "HasChildren" : false
    }
   ]
 }

 

  

Get active parent of active child

HTTP GET: /../Containers/Children/{identifier} 

Use this method to get the active parent of an active child based on the child identifier. In case of no active container, an empty response will be returned.

Child identifier will be provided in the URI { identifier } and is mandatory.

Request syntax

ChildIdentifier from uri

Response syntax

{
  "ParentUuid": string,
  "ParentIdentifier": string
}

Request example:

  GET  …./ /Containers/Children/4015468532198642

Response example:

{
  "ParentUuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
  "ParentIdentifier": "4015468532135485"
}

 

 

Get active containers

HTTP GET: /../Containers/Active?identifier={identifier}&&pageSize={pageSize}&&pageIndex={pageIndex}

Use this method to return all active first-level containers associated with the user context. In case of no active container, an empty response will be returned.

Container identifier is optional and can be provided in the URI { identifier }. If provided, the "starting with" filter will be applied to the string input.

Request syntax

• pageSize: int from Uri; optional field; default value 50. Maximum value 50.
• pageIndex: int from Uri; optional field
• identifier:string from Uri; optional field
  
  

Response syntax

[
  {  
    "Uuid": string,
    "Identifier": string
  }
]

Request example:

GET  ….//Containers/Active
GET  ….//Containers/Active?pageIndex=0
GET  ….//Containers/Active?pageIndex=0&&pageSize=15
GET  ….//Containers/Active?identifier=40154685321354
GET  ….//Containers/Active?pageIndex=0&&identifier=40154685321354
GET  ….//Containers/Active?pageIndex=0&&pageSize=15&&identifier=40154685321354

Response example:

[
  {
    "Uuid": "36FCC6EA-403B-480D-BE7E-7237B8EFF7F0",
    "Identifier": "4015468532135485"
  },
  {
    "Uuid": "241B3F4E-6D02-4EA5-A7FB-E728D4CC8148",
    "Identifier": "4015468532135400"
  }
]

 

 

Get container by identifier or uuid

HTTP GET: /ContainerWS/Public/Containers/Container?identifier={identifier}&active={active}

HTTP GET: /ContainerWS/Public/Containers/Container?uuid={uuid}&active={active}

Use this method to retrieve containers by identifier or UUID and active status. By default, the search will be done only based on active containers. In case you also want to get the inactive containers, you should use the "active" parameter with a false value.

In case no container was found based on the searching criteria provided, HttpStatus code 200 OK will be received with an empty body.

Request syntax

• identifier:string from Uri; optional parameter
• uuid:string from Uri; optional parameter
• active:bool from Uri; optional parameter; default value true

Response syntax:

 [{  
     "ContainerUuid": string,
     "ContainerIdentifier": string, 
     "LocalDate": datetime, 
     "IsActive" : bool,
     "ChildrenCount" : bool 
 }]

 

Request example:

GET  …./ /Containers/Container?identifier=40170726204100091188 
GET  …./ /Containers/Container?identifier=40170726204100091188&active=false 
GET  …./ /Containers/Container?identifier=40170726204100091188&active=true 
GET  …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d 
GET  …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d&active=false 
GET  …./ /Containers/Container?uuid=a0793270-5de8-4f6b-be1d-9321e43b703d&active=true  

Response example:

Example 1:

[
   {
      "ContainerUuid": "c208421e-a249-4d7a-ba9a-35d85de6dd01",
      "ContainerIdentifier": "40170726204100091188",
      "LocalDate": "2022-06-30T10:53:07",
      "IsActive": false,
      "ChildrenCount": 3
   },
   {
      "ContainerUuid": "6fc110ad-30cb-4166-bb3f-381813985fc5",
      "ContainerIdentifier": "40170726204100091188",
      "LocalDate": "2022-06-30T10:56:24",
      "IsActive": false,
      "ChildrenCount": 2
   },
   {
      "ContainerUuid": "fd977b22-1c17-40cd-9966-7e8b92568dce",
      "ContainerIdentifier": "40170726204100091188",
      "LocalDate": "2022-06-30T10:57:57",
      "IsActive": false,
      "ChildrenCount": 2
   }
]

 

Example 2:

[
   {
      "ContainerUuid": "a0793270-5de8-4f6b-be1d-9321e43b703d",
      "ContainerIdentifier": "40170726204100105809",
      "LocalDate": "2022-07-03T12:53:12",
      "IsActive": true,
      "ChildrenCount": 1
   }
]

 

Lock container

HTTP POST: …/Containers/{uuid}/Lock

Use this method to lock a virtual container. Once the container is locked, no children can be added to the container with the “Add Children to Container” method. A new container should be created using the “Create Container” method. The "Create container" method will not be allowed if there is another not locked container for the same template. Only one virtual container per template at a time can be locked.

Only virtual active containers created by the owner that is initiating the request can be locked. In case of at least one criteria not being met BadRequest will be returned.

If the operation succeeded HttpStatus code 200 OK will be received with an empty body.

Request syntax

containerUuid: mandatory parameter in the URI {uuid}.

    
Response syntax

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. In case the virtual container was already locked the operation will fail and BadRequest will be returned.

Request example

GET  …./ / Containers/Public/Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/Lock

Response example

HTTP 200 OK 

 

 

Unlock container

HTTP POST: … /Containers/{uuid}/Unlock

Use the method to unlock a virtual active container.

Once the container is unlocked, children can be added to the container with “Add Children to Container” method.

A virtual container can be unlocked only if there is no other virtual container with the same template not locked. Only virtual active containers created by the owner that is initiating the request can be unlocked. In case of at least one criteria not being met BadRequest will be returned.

If the operation succeeded HttpStatus code 200 OK will be received with an empty body.

 

Request syntax

• containerUuid: mandatory parameter in the URI {uuid}.

    

Response syntax

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. In case the virtual container is not locked the operation will fail and BadRequest will be returned.

Request example

GET  …./ / Containers/Public/Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/Unlock

Response example

HTTP 200 OK 

 

 

Container load status

HTTP GET: /… /Containers/{uuid}/load/status

Use the load status method to get the number of confirmed and not confirmed packages (scanned or assumptions) for the first-level children.

In case the container UUID does not exist or is inactive BadRequest will be returned. If the container was created with another ownerTag than the one from the header, Forbidden will be returned.

If the operation succeeded HTTP Status code 200 OK will be received containing the confirmed packages count and not confirmed packages count.

 

Request syntax

Container UUID will be provided as a parameter in the URI {uuid}.

 

Response syntax

If the action is successful, the service sends back an HTTP 200 response with ConfirmedCount and NotConfirmedCount.

Request example:

GET …./ /Containers/Public/Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/load/status

 

ResponseStatus

HTTP 200 OK

 

Response example:

{
   "ConfirmedCount": 0,
   "NotConfirmedCount": 1
}

 

 

Container load items

HTTP GET: /container/Public/Containers/{Uuid}/load/items?confirmed={confirmed}&pageSize={pageSize}&pageIndex={pageIndex}

Use this method to return the confirmed or not confirmed packages (scanned or assumptions) for the first-level children. In case the container UUID does not exist or is inactive BadRequest will be returned. If the container was created with another ownerTag than the one from the header, Forbidden will be returned.

If the operation succeeded HttpStatus code 200 OK will be received containing the confirmed packages items and not confirmed packages items.

 

Request syntax

• Container uuid will be provided as parameter in the URI {uuid}.
• {confirmed} - default value = true
• {pageSize} - default value = 20
• {pageIndex} - default value = 0
  
  

Response syntax

• If the action is successful, the service sends back an HTTP 200 response and the HTTP body will be received.
• ContainerIdentifier - the identifier of the parcel (package barcode)
• Uuid - the unique identifier of the container which contains the parcel
• ShipmentUuid - the unique identifier of the shipment which contains the parcel
• SubmitDate - the submit date of the shipment

{
   [{
      "ContainerIdentifier": string,
      "Uuid": guid,
      "ShipmentUuid": guid,
      "SubmitDate": datetimeoffset
   }]
}

 

Request example

Returns: processing status

GET …./Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/load/items?confirmed=false&pageSize=20&pageIndex=0 
GET …./Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/load/items?confirmed=true&pageSize=20&pageIndex=0 
GET …./Containers/a0793270-5de8-4f6b-be1d-9321e43b703d/load/items 
GET …./Containers/CB99D1A6-A8C9-4D39-A72A-963D07C9DFBF/load/items?confirmed=false&pageSize=20&pageIndex=0

 

ResponseStatus

HTTP 200 OK

 

Response example

[
   {
      "ContainerIdentifier": "Parcel1",
      "Uuid": "cdbc59fa-010c-4150-8fbd-4b9984c60ca7",
      "ShipmentUuid": "1f5bfed2-7f94-4456-8da6-40d2fb1e4805",
      "SubmitDate": "2022-06-09T12:38:10+00:00"
   },
   {
      "ContainerIdentifier": "Parcel2",
      "Uuid": "dda0c88e-cfcf-4e38-99c8-788036657262",
      "ShipmentUuid": "a339cd99-a5ac-4b2c-9b3f-7a0ce780b6ef",
      "SubmitDate": "2022-06-09T12:38:11+00:00"
   }
]

 

 

Container Confirm parent

HTTP POST: /…/Containers/{Uuid}/confirm/parent

Use this method to confirm that the specified package identifiers (scanned or assumptions) for the first level children were loaded to the specified container and that they are active.
In case the container UUID does not exist or is inactive BadRequest will be returned.

If the container was created with another ownerTag than the one from the header, Forbidden will be returned.

If the operation succeeded HttpStatus code 200 OK will be received containing the confirmed packages items and not confirmed packages items.

 

Request syntax
Container uuid will be provided as parameter in the URI {uuid}.

{
   "ChildrenIdentifier": [
   "string"
   ]
}

 

Response syntax

• If the action is successful, the service sends back an HTTP 200 response and the HTTP body will be received.
• AllConfirmed - true in case all provided identifiers belongs to the specified container; false in case at least one identifier does not belong
• NotConfirmed - the list of child identifiers that don't belong to the specified container

{
   [{
      "AllConfirmed": bool,
      "NotConfirmed": [string]
   }]
}

 

Request example
Returns: processing status

POST …./Containers/12E96B8A-70EA-447B-A2A4-F6D92A752A7F/confirm/parent 

[ 
   "470716670008093090", 
   "470716670008093205" 
] 

POST .../Containers/12E96B8A-70EA-447B-A2A4-F6D92A752A7F/confirm/parent 
Response: 200 OK 
{ 
   "AllConfirmed": false, 
   "NotConfirmed": [ 
   "470716670008093090", 
   "470716670008093205"
   ] 
} 

POST …./Containers/12E96B8A-70EA-447B-A2A4-F6D92A752A7F/confirm/parent 
[ 
   "370716670008093090", 
   "370716670008093205" 
] 

POST .../Containers/12E96B8A-70EA-447B-A2A4-F6D92A752A7F/confirm/parent 
Response: 200 OK 
{ 
   "AllConfirmed": true, 
   "NotConfirmed": [] 
}

 

 

Get owner settings

HTTP GET: /container/Public/Settings

Use this method to get the configured container settings for the owner.
In case the user is not ADMIN (carrier, customer) or OWNER (carrier, customer) Forbidden will be returned. If the user or owner is not correctly configured in User Management, Bad Request will be returned. If the operation succeeded, HttpStatus code 200 OK will be received containing the settings for the user's owner.

 

Response syntax
If the action is successful, the service sends back an HTTP 200 response and HTTP body will be received.

{
   "ClosingOption": bool
}

 

Request example
Returns: processing status

GET…./ /Containers/Public/Settings

{
   "ClosingOption" : true
}

 

 

Add or update owner settings

HTTP PUT: /container/Public/Settings

Use the Add or update owner settings method to save or update settings for a user's owner.
In case the user is not ADMIN (carrier, customer) or OWNER (carrier, customer), Forbidden will be returned.

In case the user or owner is not correctly configured in User Management, Bad Request will be returned.

In case the operation succeeded HttpStatus code 200 OK will be received containing an empty response.

 

Response syntax

If the action is successful, the service sends back an HTTP 200 response and HTTP body will be received.

{
   "ClosingOption": bool
}

 

Request example

Returns: processing status

PUT…./ /Containers/Public/Settings
{
"ClosingOption" : true
}

 

 

Get active containers count

HTTP POST: /Public/Containers/Active/Count

Get the total number of first-level active containers associated with the user context within the specified date range. The date filter will be applied considering the UTC date value greater or equal to startdate and less than enddate.

In case the user is not ADMIN (carrier, customer) or OWNER (carrier, customer) Forbidden will be returned.

If the user or owner is not correctly configured in User Management, Bad Request will be returned.

If the operation succeeded HttpStatus code 200 OK will be received containing the total number of active containers.

 

Request syntax

{
   "startdate": "datetimeoffset",
   "enddate": "datetimeoffset"
}

 

Response syntax
If the action is successful, the service sends back an HTTP 200 response and HTTP body will be received.

{
   "total": int
}

 

Request example
Returns: total number of active containers

POST../Public/Containers/Active/Count
{
   "startDate": "2022-03-01T00:33:02.991",
   "endDate": "2022-06-16T13:33:02.991"
}

 

Response

{
   2000
}

 

Further reading

• Using Containers in Scan App Pro
• Using Route planning in Scan App Pro
• API configuration setup
• Using the Container feature in nShift On-premises