9 Interventions

9.1 Intro

Intervention endpoints require Authorization.

For more visual details, refer to the swagger documentation.

9.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.

9.2 Services

9.2.1 Request Intervention Options

This endpoint allows you to get all available intervention options based upon the input parameters provided. These include:

• postalCode: A String in the format: 1000AA (required)
• parcelId: A String or array of strings (up to 20) containing tracking/parcel codes (recommended)
• id: ⚠️ DEPRECATED - Previously used for both parcelId and notHomeCode. Use parcelId parameter instead.
• details: An optional boolean that adds the potential timeframes and servicepointIds, more info on this later.

⚠️ Deprecation Notice

Using id parameter is deprecated

• Recommended: Use the parcelId parameter explicitly when providing parcel tracking codes
• The id parameter is maintained for backward compatibility but will be removed in a future version
• You can now pass multiple parcel IDs as an array (up to 20 items) using parcelId

Using notHomeCode is deprecated

• The not-home code functionality is being phased out
• Please use parcel IDs directly when possible

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 response structure contains conditional fields based on intervention availability and type. See Response Field Conditions for details on which fields appear under different conditions.

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,
                "sustainabilityRanking": 2,
                "nextTimeframe": {
                    "from": "2022-04-16T09:00",
                    "to": "2022-04-16T13:00"
                },
                "rangeStartDate": "2022-04-16",
                "lastAllowedAttempt": false
            },
            "neighboursIntervention": {
                "available": true,
                "sustainabilityRanking": 1,
                "executionTimeframe": {
                    "from": "2022-04-15T09:00",
                    "to": "2022-04-15T13:00"
                },
                "isRingDoorbellEnabled": true
            },
            "servicePointIntervention": {
                "available": true,
                "sustainabilityRanking": 1,
                "deliveryDate": "2022-04-16"
            }
        }
    }
}

9.2.1.1 Response Field Conditions

The intervention options response contains conditional fields that appear or are omitted based on availability and intervention type.

Fields Within Each Intervention Option

The following table describes which fields appear within each intervention type (agreedPlaceIntervention, dateTimeIntervention, neighboursIntervention, servicePointIntervention, cancelIntervention):

Field	Type	Present When	Description
available	boolean	Always	Whether this intervention type is available for selection
sustainabilityRanking	integer	available: true only	Sustainability score - lower values indicate more environmentally friendly options
reasons	array	available: false	Array of reason codes explaining why the intervention is unavailable. See Reason Codes
executionTimeframe	object	available: true (Agreed Place, Neighbours only)	Time window when the intervention will be executed, with from and to timestamps. May be an empty object if timeframe data is unavailable
nextTimeframe	object	available: true (Date/Time only)	Next available delivery timeframe, with from and to timestamps
deliveryDate	string	available: true (Service Point only)	Delivery date in ISO 8601 format (YYYY-MM-DD)
rangeStartDate	string	available: true (Date/Time only)	Start date of the delivery date range in ISO 8601 format
lastAllowedAttempt	boolean	Date/Time only (regardless of availability)	Indicates whether this is the last delivery attempt allowed
isRingDoorbellEnabled	boolean	available: true (Agreed Place, Neighbours only)	Whether the courier is instructed to ring the doorbell
isPhotoEnabled	boolean	available: true (Agreed Place only)	Whether photo proof of delivery is enabled

Top-Level Response Fields

The top-level response may include additional fields depending on query parameters:

Field	Type	Present When	Description
interventionOptions	object	Always	Map of parcel IDs to their available intervention options
servicepointIds	array	details=true	List of available ServicePoint IDs in format “CC-XXXXXX” (e.g., “NL-012345”). See Intervention Details
timeFrames	array	details=true	Available delivery timeframes for the next 14 days. See Intervention Details

Summary by Intervention Type

• Agreed Place: When available, includes sustainabilityRanking, executionTimeframe, isRingDoorbellEnabled, isPhotoEnabled
• Date/Time: When available, includes sustainabilityRanking, nextTimeframe, rangeStartDate; lastAllowedAttempt may appear regardless of availability
• Neighbours: When available, includes sustainabilityRanking, executionTimeframe, isRingDoorbellEnabled
• Service Point: When available, includes sustainabilityRanking, deliveryDate
• Cancel: When available, includes sustainabilityRanking
• All types: When unavailable (available: false), include reasons array with reason codes; sustainabilityRanking is NOT included

NotHomeCode (⚠️ Deprecated)

Note: The use of not-home codes is deprecated and will be removed in a future version. Please use parcel IDs directly.

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
SIGNATURE_FOR_LOCKER             225        This parcel requires a signature upon delivery and cannot be intervened to a locker
INVALID_SERVICEPOINT_ID          226        ServicePoint ID is invalid
SERVICEPOINT_HIDDEN              227        This ServicePoint is considered hidden
SERVICEPOINT_NOT_WITHIN_RADIUS   228        ServicePoint is not within radius of parcel location
NO_PHONE_NUMBER_OR_VALID_EMAIL   229        Missing/invalid phone number or email
SERVICEPOINT_IS_BUURTPUNT        230        ServicePoint is a 'Buurtpunt'
INCOMPLETE_ADDRESS               231        Parcel address is incomplete
NO_NOT_HOME_CARD_SCANNED         232        Not home code equals 'no_kib_card_scanned'
NO_NOT_HOME_CODE_IN_STATUS       233        No not home code found in not-home status
NOT_HOME_CODE_ALREADY_EXISTS     234        Not home code already exists
COORDINATES_MISSING_PARCEL       235        Parcel address coordinates were null
PDA_DISTANCE_EXCEEDS_LIMIT       236        PDA distance exceeds the limit of 200m
NOT_HOME_STATUS_NOT_PDA          237        Not home status is not of type PDA
CONSUMER_BEFORE_NH2SP            238        Consumer intervention was done before NH2SP intervention
SERVICEPOINT_CLOSES_TOO_EARLY    239        ServicePoint closes too early on delivery day
INVALID_NOT_HOME_CODE            241        Not home code was of an invalid format
OTHER_PARCEL_DID_NOT_PASS        242        Other parcel(s) did not pass validation
COORDINATES_MISSING_NH_STATUS    243        Not home status coordinates were null
COORDINATES_MISSING_ALL          244        Both address and not home status coordinates were null
NO_ADJACENT_SP                   247        This service point is not adjacent to the parcel destination
NEIGHBOURS_DISTANCE_TOO_LARGE    248        Distance to neighbours' address is too far
NEIGHBOURS_DISTANCE_UNKNOWN      249        Distance to neighbours' address is unknown

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_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_MULTIPLE_DELIVERY_ATTEMPTS 315   This parcel requires multiple delivery attempts
REASON_POSTAL_CODE_BLACKLIST            316     This type of intervention is not allowed for a parcel in this postal code area
REASON_CANCELLED                        317     The delivery or pickup of this parcel has been cancelled
REASON_IN_LAST_CONTRACT_STEP            318     The current delivery attempt is the last attempt
REASON_SORT_ERROR                       319     This parcel has been delayed, the current delivery date is uncertain
REASON_PARCEL_MEASUREMENTS_UNAVAILABLE  320     One or more of this parcel's measurements is missing
REASON_TRIP_IN_FALLBACK                 321     Intervention request can't reach the courier at this moment
REASON_SAME_DAY_DELIVERY                322     This type of intervention is not possible for planned same day delivery
REASON_PAST_THIRD_ATTEMPT_AND_NH2SP     323     Parcel is past the third delivery attempt and has a subsequent NH2SP intervention
REASON_SUNDAY_NETWORK                   324     This type of intervention is not possible for sunday delivery
REASON_DATETIME_INTERVENTION_LIMIT      325     This parcel has reached the maximum number of datetime interventions
REASON_SOS_NETWORK                      326     This type of intervention is not allowed due to logistical constraints
REASON_ADDRESS_CLOSED_PERIOD            327     Address is closed or inaccessible on the delivery date
REASON_DELIVERY_UNDERWAY                328     This type of intervention is not allowed while the delivery is underway
REASON_ADDRESS_NOT_FOUND                329     The parcel's destination does not correspond to any official address in the land registry

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).

9.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: A String in the format: 1000AA
• id: A String containing a tracking/parcelId code

More info can be found in the swagger documentation.

9.2.3 Retrieve Intervention by UUID

This endpoint allows you to retrieve the details of a specific intervention using its unique intervention ID.

Endpoint: GET /api/interventions/{id}

Path Parameters:

• id: UUID of the intervention (e.g., d290f1ee-6c54-4b01-90e6-d701748f0851)

Response Fields:

• interventionId: UUID - The unique identifier of the intervention
• pid: String - The parcel ID associated with this intervention
• status: String - Current status of the intervention
• type: String - The type of intervention
• fraudIndication: Boolean - Whether fraud is indicated for this intervention

Intervention Status Values

Status	Description
PENDING	The intervention request has been accepted and is waiting to be processed
CREATED	The intervention has been created successfully
WAITING_FOR_COURIER	The intervention has been processed but has not been sent to the courier yet
SENT_TO_COURIER	The intervention has been pushed to the courier via webhook
RETRIEVED_BY_COURIER	The intervention has been retrieved by the courier
EXPIRED	The intervention has expired

Intervention Type Values

Type	Description
AGREED_PLACE	Deliver the parcel at an agreed location
SERVICE_POINT	Deliver the parcel at a ServicePoint
DATE_TIME	Deliver the parcel at a specific date and time
NEIGHBOURS	Deliver the parcel at a neighbour’s address
CANCEL	Cancel the parcel delivery

Example Response

{
  "interventionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "pid": "JVGL05762596001542169424",
  "status": "WAITING_FOR_COURIER",
  "type": "SERVICE_POINT",
  "fraudIndication": false
}

Use Case

This endpoint is useful when you need to check the current status of an intervention after it has been created.

Obtaining the Intervention ID:

When you create a new intervention (e.g., via /interventions/agreedplace, /interventions/servicepoint, etc.), the intervention ID is returned in the response header as Location.

Example response header:

Location: https://api-gw.dhlparcel.nl/interventions/d290f1ee-6c54-4b01-90e6-d701748f0851

You can extract the UUID from this location header to use with the retrieve intervention endpoint.

9.3 API Usage

Description	URL
Get intervention options	https://api-gw.dhlparcel.nl/intervention-options
Get intervention by ID	https://api-gw.dhlparcel.nl/interventions/{id}

9.3.1 Get Intervention Options

Request Examples

Using parcelId (Recommended)

Single Parcel:

curl -X GET "https://api-gw.dhlparcel.nl/intervention-options?parcelId=JVGL06369409000381534128&postalCode=6811EV&details=false" \
  -H "Source: T&T Website" \
  -H "Accept: application/json"

Multiple Parcels:

curl -X GET "https://api-gw.dhlparcel.nl/intervention-options?parcelId=JVGL0988283838838&parcelId=JVGL0988283838837&parcelId=3S012301230&postalCode=1234AB&details=true" \
  -H "Source: T&T Website" \
  -H "Accept: application/json"

Using id parameter (Deprecated)

# ⚠️ DEPRECATED - Use parcelId parameter instead
curl -X GET "https://api-gw.dhlparcel.nl/intervention-options?id=JVGL06369409000381534128&postalCode=6811EV&details=false" \
  -H "Source: T&T Website" \
  -H "Accept: application/json"

Responses

Success (code 200)

See Intervention Options Response for detailed response structure.

Error (code 400)

Missing Source Header:

{
  "parcels": {
    "": [
      {
        "code": 215,
        "reason": "Request does not contain the mandatory Source Header",
        "order": 0
      }
    ]
  }
}

Invalid Postal Code:

{
  "parcels": {
    "JVGL123": [
      {
        "code": 208,
        "reason": "Postal code of parcel address differs from supplied postal code",
        "order": 0
      }
    ]
  }
}

9.3.2 Get Intervention by ID

Request Example

curl -X GET "https://api-gw.dhlparcel.nl/interventions/d290f1ee-6c54-4b01-90e6-d701748f0851" \
  -H "Accept: application/json"

Responses

Success (code 200)

{
  "interventionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "pid": "JVGL05762596001542169424",
  "status": "WAITING_FOR_COURIER",
  "type": "SERVICE_POINT",
  "fraudIndication": false
}

Not Found (code 404)

When the intervention ID does not exist, the endpoint returns a 404 status with no body.

9.4 Testing

All intervention endpoint testing should be performed in the acceptance environment.

The acceptance environment provides a safe testing space where you can:

• Test intervention options retrieval with various parcel states
• Verify error handling and reason codes
• Test the intervention creation flow without affecting production parcels
• Validate intervention status tracking

Please refer to the swagger documentation for interactive testing capabilities.