8 Interventions
8.1 Intro
Intervention endpoints require Authorization.
For more visual details, refer to the swagger documentation.
8.1.1 Headers
Source
The Source header is a mandatory custom header, which is expected to contain a String value that relates to the source of the user.
Technically speaking, this value can contain any possible String, but for appropriate usage, its value should be aligned with DHL’s naming convention.
Authorization
An authorization token in the header of the HTTP request is mandatory in the case of a few operations.
More details on the intricacies of the endpoints, and how to use them, can be found in the following sections.
8.2 Services
8.2.1 Request Intervention Options
This endpoint allows you to get all available intervention options based upon the input parameters provided. These include:
postalCode: AStringin the format:1000AAid: AStringcontaining either a tracking/parcelId code or a not-home codedetails: An optionalbooleanthat adds the potential timeframes and servicepointIds, more info on this later.
All Available Options:
| Intervention type | Description |
|---|---|
| agreed place | request the parcel be put in a specific place, in close proximity to the recipients house, transferring responsibility to the recipient |
| ServicePoint | change the parcel’s destination to a specific ServicePoint |
| neighbours | change the parcel’s destination to the neighbours address |
| date time | change the parcel’s delivery window to a later date/time |
The intervention options response will return:
- whether an option is available,
- the time window (or in the case of a ServicePoint intervention, the date) it would be delivered on
- if an option is not available it will return a list of reason codes instead.
Intervention Options Response
The following json is an example when the intervention-options endpoint is provided with a valid postalcode + tracking/parcel id combination.
{
"interventionOptions": {
"JVGL123": {
"agreedPlaceIntervention": {
"available": false,
"reasons": [
{
"code": 301,
"reason": "Feature no agreed place doesn't allow for this type of intervention"
},
{
"code": 303,
"reason": "This type of intervention is not allowed for a parcel that requires a signature upon delivery"
}
]
},
"dateTimeIntervention": {
"available": true,
"executionTimeframe": {
"from": "2022-04-15T09:00",
"to": "2022-04-15T13:00"
},
"nextTimeframe": {
"from": "2022-04-16T09:00",
"to": "2022-04-16T13:00"
}
},
"neighboursIntervention": {
"available": true,
"executionTimeframe": {
"from": "2022-04-15T09:00",
"to": "2022-04-15T13:00"
}
},
"servicePointIntervention": {
"available": true,
"deliveryDate": "2022-04-16"
}
}
}
}
NotHomeCode
The not home code is a unique code that the driver leaves at the residence of the recipient when the recipient is not at home to receive one or more parcels.
This code links to one or more tracking codes / parcels.
When a nothome code is passed in id, the response body will contain the intervention options of each parcel linked to the notHomeCode, plus an aggregated result.
This aggregated result is the common denominator of availability, meaning it will only show those (intervention) options that are available to all parcels linked to the notHomeCode.
Reason Codes (why an intervention option is unavailable)
When an intervention option is not available, the api returns a reason code:
- A validation reason indicates something about the request itself is wrong.
- A verification reason indicates why, according to the business logic, a certain type of intervention is unavailable.
Validation Reasons:
AGREE_WITH_TERMS_NOT_SET 201 Agree with terms not set
NO_EMAILADDRESS 202 Email address not set
INVALID_EMAILADDRESS 203 Email address invalid
INVALID_HOUSENUMBER 204 Housenumber is invalid or not set
INVALID_PLACE_DESCRIPTION 205 Place description is invalid
PARCEL_UNKNOWN 206 Parcel is unknown or not set
POSTAL_CODE_NOT_SET 207 Postal code not set
DIFFERENT_POSTAL_CODES 208 Postal code of parcel address differs from supplied postal code
SERVICEPOINT_UNKNOWN 209 Servicepoint is unknown or not set
NO_NEXT_DELIVERY 210 There is no next delivery
SERVICE_POINT_NOT_IN_REGION 211 ServicePoint not part of delivery region parcel
SERVICE_POINT_NOT_OPEN 212 ServicePoint is not open on next delivery date
NEXT_TIME_FRAME_NOT_SET 213 The next time frame is not set
NEXT_TIME_FRAME_NOT_VALID 214 The next time frame is not a delivery time frame
SOURCE_NOT_PROVIDED 215 Request does not contain the mandatory Source Header
SOURCE_INVALID 216 Mandatory Source Header provided is invalid
NOTHOME_CODE_UNKNOWN 217 No parcels were found for this KIB / NotHomeCode
SERVICEPOINT_CLOSED_PERIOD 218 ServicePoint is closed until the endDate
IDENTIFIER_INVALID 219 Identifier provided is invalid
POSTAL_CODE_INVALID 220 Postal code is invalid
JSON_NOT_DESERIALIZABLE 221 Request was not deserializable
FRAUDINDICATION_NOT_SET 222 FraudIndication not set
REQUESTBODY_INVALID 223 Request body provided is invalid
REASON_TOO_LARGE_FOR_LOCKER 224 This parcel does not fit in a locker
A few examples on this response format whenever a parcel cannot be found, or is considered invalid:
{
"parcels": {
"JVGL123": [
{
"code": 208,
"reason": "Postal code of parcel address differs from supplied postal code"
}
]
}
}
{
"parcels": {
"JVGL123": [
{
"code": 215,
"reason": "Request does not contain the mandatory Source Header"
}
]
}
}
Verification Reasons:
REASON_FEATURE_NO_AGREED_PLACE 301 Feature no agreed place doesn't allow for this type of intervention
REASON_FEATURE_PIN 302 This type of intervention is not allowed for a parcel that requires a pincode upon delivery
REASON_FEATURE_SIGNATURE 303 This type of intervention is not allowed for a parcel that requires a signature upon delivery
REASON_FEATURE_NOT_AT_NEIGHBOURS 304 This parcel has a product feature that says it cannot be delivered at a neighbours' house
REASON_RETURN_TO_SENDER 305 Interventions are not allowed for a parcel that is being returned to the consignor/shipper
REASON_SERVICEPOINT_PARCEL 306 Interventions are not allowed for a parcel that is to be delivered to a ServicePoint
REASON_INVALID_DELIVERY_DATE 307 Delivery date is in the past or non-existent
REASON_INCOMPLETE_ADDRESS 308 Address information on the parcel is incomplete
REASON_NO_ACTIVE_STATUS 309 Parcel doesn't appear to have a status indicating it's in our possession
REASON_INVALID_STATUS 310 The parcel's current status doesn't allow for interventions to be carried out
REASON_PARCEL_TOO_LARGE_OR_HEAVY 311 Parcel too large or too heavy for this type of intervention
REASON_PICKUP_ORDER 312 This type of intervention is not available for a pickup order
REASON_NO_LASTMILE_PARCEL 313 Parcel not in last mile
REASON_FEATURE_AGE_CHECK 314 This type of intervention is not allowed for a parcel that requires an age check
REASON_FEATURE_NH2SP 315 This type of intervention is not allowed for a parcel that requires a not-home-to-servicepoint action
REASON_POSTAL_CODE_BLACKLIST 316 This type of intervention is not allowed for a parcel in this postal code area
REASON_FRAUD_INDICATION 317 This parcel has a fraud indication
REASON_IN_LAST_CONTRACT_STEP 318 The current delivery attempt is the last attempt
REASON_SORT_ERROR 319 This parcel is delayed. Current delivery date is uncertain
REASON_TRIP_IN_FALLBACK 321 intervention (request) can't reach the courier at this moment
REASON_SAME_DAY_DELIVERY 322 This parcel needs to be delivered today
Intervention Details
Additional details can be retrieved such as a list of available ServicePoints, or delivery timeframes, by adding the details parameter.
When no details parameter is passed, it is equivalent to passing false.
The details query parameter can hold the following values:
| Parameter | Description | |
|---|---|---|
| false | No extra’s, just the intervention options proper. | default |
| true | adding both the ServicePoint id’s and the timeframes to the response |
In addition to the Intervention Options Response, the following data is aggregated with details set to true.
{
"interventionOptions": {},
"servicepointIds": [
"NL-727281",
"NL-827281",
"NL-997281"
],
"timeFrames": [
{
"from": "2022-04-15T09:00",
"to": "2022-04-15T13:00"
},
{
"from": "2022-04-16T09:00",
"to": "2022-04-16T13:00"
},
{
"from": "2022-04-17T09:00",
"to": "2022-04-17T13:00"
}
]
}
- ServicePoint Id’s can be used with the ServicePoint locator API, to retrieve the:
- Opening times
- Address
- Location data
- Additional information.
- Timeframes for a chosen postal code, indicate in which timeslots DHL will deliver in a certain postal code area/district. The returned timeframes are 14 days into the future (including today).
8.2.2 Details endpoint
These details (ServicePoint id’s and delivery timeframes), can also be retrieved individually, without the intervention options.
For these endpoints you merely require:
postalCode: AStringin the format:1000AAid: AStringcontaining a tracking/parcelId code
More info can be found in the swagger documentation.