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
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 |
/Containers/ |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/ |
N/A |
N/A |
YES |
N/A |
N/A |
|
/Containers/{Uuid}/Close/ |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Events/ |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Children/Count/ |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Children/ |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/children/{identifier} |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/Active?identifier={ identifier}&pageSize={pageSize}&pageIndex={pageIndex} |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Lock/ |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Lock/ |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/Lock/ |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/load/status |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/{Uuid}/load/items?confirmed={confirmStatus}&pageSize={pageSize}&pageIndex={pageIndex} |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Containers/{uuid}/confirm/parent |
N/A |
YES |
N/A |
N/A |
N/A |
|
/Settings |
YES |
N/A |
N/A |
N/A |
N/A |
|
/Settings |
N/A |
N/A |
YES |
N/A |
N/A |
|
/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
}