logo

Receptacles service

Imports and retrieves receptacle data

Import receptacles

Imports inbound receptacles.

Access to this method is authorized by the Import receptacles operation.

This API method corresponds to the receptacle import interface. The structure of the request body corresponds to the element of the interface XML schema. For more information, see the IPS Import/Export Administration Guide.

Note:If you want to import outbound receptacles, you can do this as part of creating dispatches.

Securityips_token
Request
query Parameters
evaluateSampling
boolean

Indicates if the receptacle should be evaluated for sampling. Not possible to combine with 'sample' parameter. If not provided considered as False.

sample
boolean

Indicates if the receptacle being imported has been evaluated for sampling and determined to be sampled. Not possible to combine with 'evaluateSampling' parameter. If not provided considered as False.

Request Body schema: application/json
ReceptacleId
required
string <= 29 characters ^[A-z0-9]{29}$

Receptacle Identifier. Allowed values: S9 UPU receptacle identifier

Weight
required
number <float> ^[0-9]{5}\.[0-9]{3}$

Receptacle weight

DocumentationEnclosed
string <= 1 characters

Indicates that the receptacle contains documentation

Enum: "0" "1"
MailSubclassFcd
required
string <= 2 characters ^[A-z0-9]{2}$

Valid receptacle mail subclass (from code list 117)
If not provided, the receptacle mail subclass defaults to the dispatch mail subclass.

CharacteristicCd
string <= 1 characters ^[A-z0-9]{1}$

Receptacle characteristic

Enum: "B" "E" "I" "M" "O" "V"
SubtypeCd
string <= 2 characters ^[A-z0-9]{2}$

Receptacle subtype

MailItmsNo
integer
RegNo
integer
InsNo
integer
PostalStatusFcd
string <= 4 characters ^[A-z0-9]{4}$

Indicates that the receptacle contains documentation

RecptclContentFormat
string <= 1 characters ^[A-z0-9]{1}$

Valid receptacle content format (from code list 120)

SamplingOfficeFCd
string
SamplingRuleId
string <guid>

IPS Sampling rule ID
Allowed only when sample parameter is true and needs to be combined with SamplingRuleLastModifiedGmt

Introduced in IPS 2022 SP1

SamplingRuleLastModifiedGmt
string <date-time>

IPS Sampling rule last modified GMT
Allowed only when sample parameter is true and needs to be combined with SamplingRuleId
Format: yyyy-MM-ddTHH:mm:ss.fffffff

Introduced in IPS 2022 SP1

SealNo
string <= 15 characters
object (InboundInfo)
ReceptacleTareWeight
number <float> ^[0-9]{5}\.[0-9]{3}$

Receptacle tare weight

Array of objects (Events)
Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/ReceptaclesService.svc/rest/receptacles
Request samples
application/json
{
  • "ReceptacleId": "NLAMSAITLINAAUN10231002000210",
  • "Weight": 45.657,
  • "DocumentationEnclosed": "1",
  • "MailSubclassFcd": "UN",
  • "CharacteristicCd": "B",
  • "SubtypeCd": "BG",
  • "MailItmsNo": 10,
  • "RegNo": 2,
  • "InsNo": 2,
  • "PostalStatusFcd": "MINL",
  • "RecptclContentFormat": "X",
  • "SamplingOfficeFCd": "string",
  • "SamplingRuleId": "70E82B62-8396-4005-8769-C636794E29C1",
  • "SamplingRuleLastModifiedGmt": "2022-01-30T08:06:58.1234567",
  • "SealNo": "string",
  • "InboundInfo": {
    },
  • "ReceptacleTareWeight": "3.4",
  • "Events": [
    ]
}
Response samples
application/json
{
  • "Receptacle": {
    }
}

Get receptacle data

Retrieves receptacle data.

Access to this method is authorized by the Get receptacles operation.

List of search parameters is in URL query string format, combined in a logical AND.

Securityips_token
Request
query Parameters
receptacleId
string

S8 standard identifier.

Not mandatory, although if not specified, must specify either lastEventGMTFrom/To or lastEventCaptureGMTFrom/To instead

originCountry
string

Two character country code, not needed if origin operator is specified

originOperator
string

Three character operator code

destinationCountry
string

Two character country code, not needed if destination operator is specified

destinationOperator
string

Two character operator code

originOffice
string

Six character office code from UPU code list 108

destinationOffice
string

Six character office code from UPU code list 108

mailCategory
string

Mail category A, B, C or D

Enum: "A" "B" "C" "D"
mailClass
string

Mail class U, C or E, not needed if the mail subclass is specified

Enum: "U" "C" "E"
mailSubClass
string

Value from UPU code list 117

lastEventGMTFrom
string <date-time>

Receptacles with last event on or after this date and time, in format YYYY-MM-DDThh:mm:ss.sss

Not mandatory, although must specify lastEventGMTFrom/To or lastEventCaptureGMTFrom/To if no receptacle ID is specified

lastEventGMTTo
string <date-time>

Receptacles with last event before this date and time, in format YYYY-MM-DDThh:mm:ss.sss

Not mandatory, although must specify lastEventGMTFrom/To or lastEventCaptureGMTFrom/To if no receptacle ID is specified

lastEventCaptureGMTFrom
string <date-time>

Receptacles with last event capture date on or after this date and time, in format YYYY-MM-DDThh:mm:ss.sss

Not mandatory, although must specify lastEventGMTFrom/To or lastEventCaptureGMTFrom/To if no receptacle ID is specified

lastEventCaptureGMTTo
string <date-time>

Receptacles with last event capture date before this date and time, in format YYYY-MM-DDThh:mm:ss.sss

Not mandatory, although must specify lastEventGMTFrom/To or lastEventCaptureGMTFrom/To if no receptacle ID is specified

Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/ReceptaclesService.svc/rest/receptacles
Response samples
application/json
{
  • "Receptacles": [
    ]
}

Security checks

Retrieves security checks performed in IPS.

Access to this method is authorized by the Retrieve receptacles operation.

Securityips_token
Request
query Parameters
Barcode
required
string = 26 characters ^[0-9]{5}-[0-9]{5}-[0-9]{14}$

Security check barcode

Example: Barcode=00856-00024-20220509110317
Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/ReceptaclesService.svc/rest/securitychecks
Response samples
application/json
{
  • "SecurityChecks": [
    ]
}

Import receptacles and mail items

Access to this method is authorized by the Import inbound receptacle and mailitems operation.

Error

In addition to the standard error codes described in Response codes, the IPS API returns a 404 error code for specific error cases, with additional error information as listed in the table below.

Code Description
1 General error.
2 Mandatory value not provided.
3 A property value in the request contains an invalid value or is in the wrong format.
4 Duplicate mail item identifiers.
5 Not applicable for specified mail class.
Securityips_token
Request
query Parameters
allowFurtherScanning
boolean

Indicates if further items are expected to be scanned (de-nested) subsequently for this receptacle. If set to true, no (auto) VN/s will be created until scanning is done for this receptacle (until value is set to false). If not provided considered as False.

evaluateSampling
boolean

Indicates if the receptacle should be evaluated for sampling. If not provided considered as False.

allowUpdateReceptacle
boolean

Indicates if the receptacle characteristics should be updated if the receptacle already exists. If not provided considered as False.

Request Body schema: application/json
ReceptacleId
required
string <= 29 characters ^[A-z0-9]{29}$

Receptacle Identifier. Allowed values: S9 UPU receptacle identifier

ConditionCd
number <integer>

Receptacle condition

Weight
number <float>

Receptacle weight

MailSubClassFCd
string <= 2 characters ^[A-z0-9]{2}$

Receptacle mail subclass

ReceptacleSubTypeCd
string <= 2 characters ^[A-z0-9]{2}$

Receptacle subtype

ReceptacleContentFormatCd
string <= 1 characters ^[A-z0-9]{1}$

Receptacle content format

Exempt
boolean

Receptacle exempt indicator. If not provided considered as False.

required
object
Array of objects
Array of objects
Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/ReceptaclesService.svc/rest/receptacleAndItems
Request samples
application/json
{
  • "ReceptacleId": "NLAMSAITLINAAUN10231002000210",
  • "ConditionCd": 20,
  • "Weight": 45.657,
  • "MailSubClassFCd": "UN",
  • "ReceptacleSubTypeCd": "BG",
  • "ReceptacleContentFormatCd": "E",
  • "Exempt": true,
  • "EventInformation": {
    },
  • "IdentifiedItems": [
    ],
  • "Bundles": [
    ]
}
Response samples
application/json
{
  • "EvaluatedForSampling": true,
  • "Info": [
    ],
  • "SamplingMessage": "string",
  • "SelectedForSampling": true,
  • "VNs": {
    }
}

Import sampled receptacles

Access to this method is authorized by the Import sampled receptacles operation.

Code Description
1 General error.
2 A property value in the request contains an invalid value or is in the wrong format.
3 Mandatory value not provided.
4 Weights don't add up properly.
5 Sampling receptacle not found.
6 Sampling receptacle not in state 'Sampling to be done'.
7 Failure storing the sampled receptacle.
Securityips_token
Request
Request Body schema: application/json
required
Array of objects
Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/ReceptaclesService.svc/rest/sampledReceptacles
Request samples
application/json
{
  • "SamplingReceptacles": [
    ]
}
Response samples
application/json
{
  • "Errors": [
    ]
}

Import external receptacles

Access to this method is authorized by the Import external receptacles operation.

Error

In addition to the standard error codes described in Response codes, the IPS API returns a 404 error code for specific error cases, with additional error information as listed in the table below.

Code Description
1 General error.
2 Mandatory value not provided.
3 A property value in the request contains an invalid value or is in the wrong format.
Securityips_token
Request
Request Body schema: application/json
required
Array of objects
Responses
200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/ReceptaclesService.svc/rest/externalReceptacles
Request samples
application/json
{
  • "ExternalReceptacles": [
    ]
}
Response samples
application/json
{
  • "Response": [
    ]
}
➔ Next to Reference data service