Reference data service

Retrieves reference data

Mail categories

Retrieves all mail categories defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/mailcategories

Response samples

application/json

{"MailCategories": [{"MailCategoryCd": "A",
"MailCategoryNm": "Air",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Mail classes

Retrieves all mail categories defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/mailclasses

Response samples

application/json

{"MailClasses": [{"MailClassCd": "C",
"MailClassNm": "PARCELS (CP)",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Mail item categories

Retrieves the mail item categories defined in IPS.

Securityips_token

Request

query Parameters

MailClass

string (MailClassCd)

Filter mail item categories that apply only to the provided mail class

Enum: "C" "E" "T" "U"

Example: MailClass=U

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/mailitemcategories

Response samples

application/json

{"MailItemCategories": [{"MailItemCategoryCd": "IN",
"MailItemCategoryNm": "Insured",
"MailClasses": [{"mailClassCd": "U"
}
],
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Mail subclasses

Retrieves all mail categories defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/mailsubclasses

Response samples

application/json

{"MailSubClasses": [{"MailSubclassCd": "UN",
"MailClassNm": "LETTERS - LC/AO",
"MailClassCd": "U",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Conveyance types

Retrieves all conveyance types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/conveyancetypes

Response samples

application/json

{"ConveyanceTypes": [{"ConveyanceTypeCd": "P",
"MailClassNm": "Priority mail",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Product types

Retrieves all product types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/producttypes

Response samples

application/json

{"ProductTypes": [{"ProductTypeCd": "P",
"MailClassCd": "C",
"ProductTypeNm": "EPG",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Receptacle content formats

Retrieves all product types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/receptaclecontentformats

Response samples

application/json

{"ReceptacleContentFormats": [{"ReceptacleContentFormatCd": "P",
"ReceptacleContentFormatNm": "Small",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Receptacle types

Retrieves the receptacle types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/receptaclesubtypes

Response samples

application/json

{"ReceptacleSubtypes": [{"ReceptacleSubtypeCd": "BG",
"ReceptacleSubtypeNm": "Bag",
"ReceptacleTypeMaxWeight": 12345.123,
"ReceptacleSubTypeWeight": 12345.123,
"ParentRecetacleTypeCd": "st",
"ValidInd": 1,
"SampleRateCd": "B1",
"TareMinWeight": 12345.123,
"TareMaxWeight": 12345.123,
"ReceptacleCategoryCd": "BG",
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Conditions

Retrieves the conditions defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/conditions

Response samples

application/json

{"Conditions": [{"ConditionCd": 20,
"ConditionNm": "Received here in good condition",
"MailUnitTypeCd": "MI",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Postal statuses

Retrieves the conditions defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/postalstatuses

Response samples

application/json

{"PostalStatuses": [{"PostalStatusCd": 0,
"PostalStatusNm": "Normal",
"MailUnitTypeCd": "MI",
"PostalStatusFCD": "MINL",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Service indicators

Retrieves the conditions defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/serviceindicators

Response samples

application/json

{"ServiceIndicators": [{"ServiceIndicatorMin": "RA",
"ServiceIndicatorMax": "RZ",
"MailClassCd": "U",
"MailItemCategoryCd": "RG",
"ConveyanceTypeCd": "P",
"ProductTypeCd": "s",
"MailitemContentCd": "BG",
"CodIndicator": 0,
"ExpressInd": 0
}
]
}

Event types

Retrieves the event types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/eventtypes

Response samples

application/json

{"EventTypes": [{"EventTypeCd": 1,
"EventTypeNm": "Receive item from customer (Otb)",
"MailUnitTypeCd": "MI",
"InboundOutboundInd": "O",
"ResultStateIndCd": 0,
"ValidInd": 1,
"AllowedInitialStates": [{"StateIndCd": 3
}
],
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

State indicators

Retrieves the state indicators defined in IPS. Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/stateinds

Response samples

application/json

{"State": [{"StateIndCd": 1,
"StateIndNm": "Unassigned (not in a bag)",
"MailUnitTypeCd": "MI",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Currencies

Retrieves the currencies defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/currencies

Response samples

application/json

{"Currencies": [{"CurrencyCd": "AED",
"CurrencyNm": "UAE Dirham",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Countries

Retrieves the countries defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/countries

Response samples

application/json

{"Countries": [{"CountryCd": "AM",
"CountryNm": "ARMENIA",
"ValidInd": 1,
"Latitude": -4000,
"Longitude": 4500,
"EuEntranceDt": "2019-08-24",
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Customs office types

Retrieves the customs office types defined in IPS.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/customsofficetypes

Response samples

application/json

{"CustomOfficeTypes": [{"CustomsOfficeTypeCd": "OE",
"CustomsOfficeTypeNm": "At the office of exchange; default value",
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Customs release statuses

Retrieves the custom release statuses defined in IPS.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/customsreleasestatuses

Response samples

application/json

{"CustomsReleaseStatuses": [{"CustomsReleaseStatusCd": "EA",
"CustomsReleaseStatusNm": "Export authorized",
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Sampling rules

Retrieves the sampling rules defined in IPS. Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/samplingrules

Response samples

application/json

{"SamplingRules": [{"DateFrom": "2019-08-24",
"DateTo": "2019-08-24",
"OrigOperatorCd": "str",
"OrigOfficePartCd": "FRCDGA",
"DestOperatorCd": "str",
"DestOfficePartCd": "FRCDGA",
"MailCategoryCd": "A",
"MailClassCd": "U",
"MailSubClassFCd": "UN",
"AdditionalBagCharac": 0,
"DispatchNo": "string",
"ReceptacleSerialNo": "string",
"SamplingAction": "string",
"RuleNationalInd": 0,
"SamplingRate": 0,
"ReceptacleSubTypeCd": "BG",
"ReceptacleContentFormatCd": "E",
"SelectRandomlyInd": 0,
"UseForSampling": true,
"ReceptacleCategoryCd": "BG",
"LastModifiedGmt": "2022-01-30T08:06:58.1234567"
}
]
}

Postal operators

Retrieves the postal operators defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/operators

Response samples

application/json

{"Operators": [{"OperatorCd": "AMA",
"OperatorLongNm": "Haypost AM",
"OperatorShortNm": "ARMENIA",
"ValidInd": 1,
"PaymentMethodCd": "DR",
"EmailAddress": "string",
"PostalAddress": "string",
"EtoeSeparateInd": "N",
"NumberSamplingDays": "N",
"CountriesList": [{"CountryCD": "AM"
}
]
}
]
}

Airlines

Retrieves the airlines defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/airlines

Response samples

application/json

{"Airlines": [{"AirlineCd": "LX",
"AirlineNm": "SWISS International Air Lines Ltd",
"ValidInd": 1
}
]
}

IMPCs

Retrieves the IMPCs defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/impcs

Response samples

application/json

{"Impcs": [{"OfficeFcd": "CAYTOA",
"OfficeLongNm": "TORONTO-A",
"OfficeShortNm": "TORONTO-A",
"CountryCd": "CA",
"OperatorCd": "CAA",
"ValidInd": 1,
"EmailAddress": "string",
"PostalAddress": "string",
"Restrictions": "string",
"ValidFrom": "2003-10-04",
"ValidTo": "",
"DispatchesRoutedVia": "string",
"SpecialType": "",
"BilateralAgreementRequired": 0,
"MailFlows": [{"MailFlowCd": "I"
}
],
"MailCategoriesInbound": [{"MailCategoryCd": "A"
}
],
"MailClassesInbound": [{"MailClassCd": "U"
}
],
"MailCategoriesOutbound": [{"MailCategoryCd": "A"
}
],
"MailClassesOutbound": [{"MailClassCd": "U"
}
],
"OfficeTypes": [{"OfficeTypeCd": "OOE"
}
]
}
]
}

Locations

Retrieves the locations defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

The addition of parameters for filtering ref data API results for Locations was released in package 6 of IPS 2024 SP1.

In addition to the standard error codes described in Response codes, the IPS API returns a 400 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	Invalid reference data

Securityips_token

Request

query Parameters

CountryCd	string = 2 characters Returns locations with the country code provided. This parameter should be 2 characters. NOT validated as valid country (in C_COUNTRIES). If the country does not exist, the API returns EMPTY list of locations. Example: CountryCd=IT
ValidInd	number <= 1 characters ^[0-3]$ Returns locations whose VALID_IND is exactly the parameter value as per the following 0 – Official reference data (invalid) 1 - Official reference data (valid) 2 – Own reference data (invalid) 3 - Own reference data (valid) Enum: 0 1 2 3 Example: ValidInd=1
LocationStatusCd	string Returns locations whose LOCATION_STATUS_CD is exactly the parameter value. The paramter value should be a valid location status code (in C_LOCATION_STATUS).

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/locations

Response samples

application/json

{"Locations": [{"LocationFcd": "CAYTO",
"CountryCd": "CA",
"LocationCd": "YTO",
"LocationNm": "Metropolitan Area Apt/Toronto",
"LocationStatusCd": "AI",
"SuspendedInd": 0,
"ValidInd": 1,
"IataInd": 0,
"Latitude": 0,
"Longitude": 0,
"CutoffAtOrigin": 0,
"CutoffAtDestination": 0,
"MinimumTransitTime": 0,
"LocationTypes": [{"LocationTypeCd": "0"
}
]
}
]
}

Location types

Retrieves the location types defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/locationtypes

Response samples

application/json

{"LocationTypes": [{"LocationTypeCd": "4",
"LocationTypeNm": "Airport",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Location statuses

Retrieves the location statuses defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/locationstatuses

Response samples

application/json

{"LocationStatuses": [{"LocationStatusCd": "AA",
"LocationStatusNm": "Approved by government",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Own offices

Retrieves the own offices defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/ownoffices

Response samples

application/json

{"OwnOffices": [{"OwnOfficeCd": 0,
"OfficeFCD": "CAYTOA",
"OfficeNm": "TORONTO-A",
"DbServerNm": "string",
"ValidInd": 1,
"PhoneNo": "string",
"Comments": "string",
"HouseNumber": "string",
"AddressLine1": "string",
"AddressLine2": "string",
"Postcode": "string",
"City": "string",
"CustomsOfficeCd": "string",
"CustomsOfficeTypeCd": "OE",
"Locations": [{"LocationFcd": "CAYTOA"
}
],
"MailSubclasses": [{"MailSubclassFcd": "UN"
}
],
"OfficeTypes": [{"OfficeTypeCd": "OOE"
}
],
"NextOffices": [{"NextOfficeFCd": "CAYTOA",
"NextOfficeQualifier": "I"
}
]
}
]
}

Import own offices

Import own offices.

Access to this method is authorized by the Import Own Offices operation.

This functionality was released in package 7 of IPS 2024 SP1.

Error

In addition to the standard error codes described in Response codes, the IPS API returns a 400 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	Invalid reference data

Securityips_token

Request

Request Body schema: application/json

OfficeFCd required	string <= 25 characters ^[A-z0-9]{25}$ The office code. If that office doesn't exist in the IPS database, the API will CREATE this office with the supplied details. If that office already exists in the IPS database, the API will UPDATE this office with the supplied details.
OfficeNm	string <= 64 characters ^[A-z0-9]{64}$ The office name. Mandatory when creating the office.
AddressLine1	string <= 105 characters ^[A-z0-9]{105}$ Office address – line 1
AddressLine2	string <= 105 characters ^[A-z0-9]{105}$ Office address – line 2
HouseNumber	string <= 30 characters ^[A-z0-9]{30}$ The house number of the office address
Postcode	string <= 17 characters ^[A-z0-9]{17}$ Office postcode
City	string <= 32 characters ^[A-z0-9]{32}$ Office city
PhoneNo	string <= 64 characters ^[A-z0-9]{64}$ The phone number of the office
Comments	string <= 256 characters ^[A-z0-9]{256}$ Free text comments
DbServerNm	string <= 32 characters The IPS databsase server where data for this office is located (in case of distributed IPS architecture). Can be empty
IsValid	boolean Whether the office is valid or not
CustomsOfficeCd	string <= 25 characters ^[A-z0-9]{25}$ The customs office associated to the office. OfficeFCd of an office associated to the "Customs office" type
CustomsOfficeTypeCd	string <= 3 characters The type of customs office which the office is associated to OE - At the office of exchange; default value R - Remote Customs, i.e. Customs in the domestic network, no return to the Inward OE ROE - Remote to the OE with return to the OE for injection into the domestic network Enum: "OE" "R" "ROE"
	Array of objects
	Array of objects
	Array of objects (OfficeTypes)
	Array of objects (NextOffices)

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/RefDataService.svc/rest/ownoffices

Request samples

Payload

application/json

{"OfficeFCd": "CAYTOA",
"OfficeNm": "TORONTO-A",
"AddressLine1": "string",
"AddressLine2": "string",
"HouseNumber": "string",
"Postcode": "string",
"City": "string",
"PhoneNo": "string",
"Comments": "string",
"DbServerNm": "string",
"IsValid": true,
"CustomsOfficeCd": "string",
"CustomsOfficeTypeCd": "OE",
"Locations": [{"LocationFCd": "CAYTOA"
}
],
"MailSubclasses": [{"MailSubclassFCd": "UN"
}
],
"OfficeTypes": [{"OfficeTypeCd": "OOE"
}
],
"NextOffices": [{"NextOfficeFCd": "CAYTOA",
"NextOfficeQualifier": "I"
}
]
}

Response samples

application/json

{"Receptacle": {"OfficeFCd": "CAYTOA",
"OfficeNm": "TORONTO-A",
"AddressLine1": "string",
"AddressLine2": "string",
"HouseNumber": "string",
"Postcode": "string",
"City": "string",
"PhoneNo": "string",
"Comments": "string",
"DbServerNm": "string",
"IsValid": true,
"CustomsOfficeCd": "string",
"CustomsOfficeTypeCd": "OE",
"Locations": [{"LocationFCd": "CAYTOA"
}
],
"MailSubclasses": [{"MailSubclassFCd": "UN"
}
],
"OfficeTypes": [{"OfficeTypeCd": "OOE"
}
],
"NextOffices": [{"NextOfficeFCd": "CAYTOA",
"NextOfficeQualifier": "I"
}
]
}
}

Retention reasons

Retrieves the retention reasons defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/retentionreasons

Response samples

application/json

{"RetentionReasons": [{"RetentionReasonCd": 19,
"RetentionReasonNm": "Prohibited articles",
"ValidInd": 1,
"Translations": [{"LanguageCD": "FR",
"Translation": "Aérien"
}
]
}
]
}

Transport companies

Retrieves the transport companies defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/transportcompanies

Response samples

application/json

{"TransportCompanies": [{"transportCompanyCd": "TC1",
"transportCompanyNm": "Transport company 1",
"transportTypeCd": "TK",
"vatWithinEu": true,
"validInd": 1
}
]
}

EDI addresses

Retrieves the EDI addresses defined in IPS.

Access to this method is authorized by the Get Reference Data operation.

Securityips_token

Responses

200

Success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/RefDataService.svc/rest/ediaddresses

Response samples

application/json

{"ediaddresses": [{"MessageType": "CARDIT",
"CountryCd": "IT",
"CarrierCd": "LX",
"OperatorCd": "FRA",
"MailClassCd": "C",
"MailCategoryCd": "A",
"MessageVersion": 2.1,
"EdiAddress": "GLG11",
"CapeInd": 1,
"ReportInd": 1,
"validInd": 1,
"ProductTypeCd": "P",
"TransportTypeCd": "PL"
}
]
}

➔ Next to Reprint forms and labels service