logo

Routing plan service

Retrieves and modify routing plans

Create and update route schedules

Creates and update route schedules

Access to this method is authorized by the Manage routing plans operation.

When creating a route, the internal identifier shall not be supplied: the caller shall only specify the mandatory request parameters and the ones for which a value is to be set. When editing an existing route, the internal identifier must be supplied alongside with the parameters whose value shall be changed: all other properties for which no request parameter is specified shall remain unchanged, with the exception of:

  • InvalidFrom
  • InvalidTo
  • WeightLimit
  • CN70Template

For the above properties, if a value has been set then it must be supplied whenever updating the route, else the value will be cleared. If a call is made omitting the internal identifier and specifying characteristics of a route that already exists, a duplicate route will be created. The same applies to the creation of segments within a route.

Business rules

  • The mail categories and mail subclasses allowed for a route are those supported by both origin and destination IMPC codes for that route, as per configuration in National Management > Partners > Postal operators and offices > Offices
  • ValidFrom must not be after ValidTo (both for route and segment validity)
  • The validity range of a route cannot exceed the one of all transport segments associated to the route.
  • InvalidFrom must not be after InvalidTo, and both must be within the date interval of ValidFrom and ValidTo
  • When creating a route, at least one transport segment must be specified
  • If an existing transport segment has to be linked to a route, only its internal identifier shall be provided: if both the internal identifier and other properties of a segment are supplied, the latter will be ignored.
  • If one or more transport segments are specified when editing a route, they will replace the transport segment(s) previously stored for that route
  • The sequence numbers of the transport segments specified for a route must be sequential and start from 0.

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 Generic error
2 Mandatory value is missing
3 The request contains inconsistent data
4 Provided value has incorrect format
5 Value does not exists in IPS DB or is marked as invalid
Securityips_token
Request
Request Body schema: application/json
RouteId
string <guid>

Internal route identifier. Must be supplied only when updating an existing route.

OriginOfficeFCd
string = 6 characters

IMPC code of the origin office. Required when creating a route.

DestOfficeFCd
string = 6 characters

IMPC code of the destination office. Required when creating a route.

MailCategories
string <= 4 characters ^[ABCD]{1,4}$

Combination of mail categories supported by the route (A, B, C, D). Required when creating a route.

MailSubclassFCds
Array of strings

List of mail subclass codes supported by this route. Required when creating a route.

OperatingDays
string^[MTWTFSS-]{7}$

Operating days of the route. Use '-' for non-operating days. For example, "M-W-T--" means operates on Monday, Wednesday, and Friday. Required when creating a route.

ValidFrom
string <date>

Start date when this route becomes valid. Required when creating a route. Format: yyyy-DD-mm

ValidTo
string <date>

End date when this route is valid. Required when creating a route. Format: yyyy-DD-mm

InvalidFrom
string <date>

Optional start of the period during which this route is invalid. Must be provided when updating a route schedule, otherwise will be set to null. Must fall within ValidFrom and ValidTo. Format: yyyy-DD-mm

InvalidTo
string <date>

Optional end of the period during which this route is invalid. Must be provided when updating a route schedule, otherwise will be set to null. Must fall within ValidFrom and ValidTo. Format: yyyy-DD-mm

WeightLimit
integer <= 999999999

Max weight in kg allowed on the route. Must be provided when updating a route schedule, otherwise will be set to null.

AlternateInd
integer
Default: 0

0: Regular route (default), 1: Alternate route used only when regular one is unavailable.

Enum: 0 1
DomesticInd
integer
Default: 0

1: Domestic route, 0: International (default).

Enum: 0 1
SuspendedInd
integer
Default: 0

0: Active (default), 1: Suspended route.

Enum: 0 1
CN70Template
string <= 7 characters

Optional CN70 template code to override national or office-level settings. Must be a valid CN70 code defined in IPS. Must be provided when updating a route schedule, otherwise will be set to null.

PrintCN70
boolean
Default: false

Whether to print CN70 document when closing consignments (true), or only include in CARDIT message (false).

ReceptacleTypes
Array of strings

Allowed receptacle types. If empty, all types are allowed. Values must be valid receptacle codes in IPS.

Array of objects

Mandatory when creating a route. Up to 5 segments allowed. If segments are provided during update, they replace the existing ones.

Responses
200

Success

400

Bad Request

post/RoutingPlanService.svc/rest/routes
Request samples
application/json
{
  • "RouteId": "2DEEE2CF-734B-4E0C-B888-605BDD9FE783",
  • "OriginOfficeFCd": "CHZRHB",
  • "DestOfficeFCd": "NLAMSA",
  • "MailCategories": "AB",
  • "MailSubclassFCds": [
    ],
  • "OperatingDays": "MTWTFSS",
  • "ValidFrom": "2025-07-01",
  • "ValidTo": "2025-12-31",
  • "InvalidFrom": "2025-09-10",
  • "InvalidTo": "2025-09-15",
  • "WeightLimit": 2000,
  • "AlternateInd": 0,
  • "DomesticInd": 0,
  • "SuspendedInd": 0,
  • "CN70Template": "CN70_R1",
  • "PrintCN70": false,
  • "ReceptacleTypes": [
    ],
  • "TransportSegments": [
    ]
}
Response samples
application/json
{
  • "Routes": [
    ]
}

Get route schedules

Retrieves route schedules.
Access to this method is authorized by the Get routing plans operation.

Securityips_token
Request
query Parameters
routeId
string <uuid>

The route internal identifier (GUID format)

Example: routeId=2DEEE2CF-734B-4E0C-B888-605BDD9FE783
originOfficeFCd
string

Origin IMPC code of the route (6-character string)

Example: originOfficeFCd=CHZRHB
destOfficeFCd
string

Destination IMPC code of the route (6-character string)

Example: destOfficeFCd=NLAMSA
mailCategories
string <= 4 characters

Mail categories supported by the route. Can be any combination of A, B, C, and D (up to 4 characters)

Example: mailCategories=AB
mailSubClassFCds
string

Comma-separated list of 2-character mail subclass codes

Example: mailSubClassFCds=UA,UL,UM,UN
operatingDays
string

Days of the week the route operates. Use 7-character string with '-' for non-operational days (e.g., M-W-T---)

Example: operatingDays=M-W-T--
validFrom
string <date>

Date from which the route is valid (YYYY-MM-DD)

Example: validFrom=2025-07-01
validTo
string <date>

Date until which the route is valid (YYYY-MM-DD)

Example: validTo=2025-12-31
alternateInd
integer

Indicates if route is alternate (1) or regular (0)

Enum: 0 1
Example: alternateInd=0
domesticInd
integer

Indicates if route is domestic (1) or international (0)

Enum: 0 1
Example: domesticInd=0
suspendedInd
integer

Indicates if route is active (0) or suspended (1)

Enum: 0 1
Example: suspendedInd=0
Responses
200

Success

400

Bad Request

get/RoutingPlanService.svc/rest/routes
Response samples
application/json
{
  • "Routes": [
    ]
}

Delete route schedule

Delete route schedule

Access to this method is authorized by the Manage routing plans operation.

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 Generic error
2 Invalid route identifier
3 Route not found
4 Failed to delete route
Securityips_token
Request
path Parameters
routeId
required
string <uuid>

The internal route identifier (GUID format)

Example: 2DEEE2CF-734B-4E0C-B888-605BDD9FE783
query Parameters
deleteSegments
boolean

Indicates whether IPS should also delete the transport segments linked to the route, provided that they are not linked to any other route. If the deleteSegments parameter is specified with a value of True, then IPS will delete any segment linked to the route which is not linked to any other route. If the deleteSegments parameter is omitted or specified with a value of False, then the segments will NOT be deleted.

Responses
200

Success

400

Bad request

404

Route schedule not found

500

Failed to delete

delete/RoutingPlanService.svc/rest/routes/{routeId}
Response samples
application/json
{
  • "Errors": [
    ]
}
➔ Next to Track and trace service