6 Pickup Requests

6.1 Intro

The Pickup Request services allow you to:

schedule a parcel pickup,
retrieve pickup requests, including status if available,
retrieve a pickup request by id.

Pickups should be requested for any date after the date the pickup request was made.

Pickup status

When retrieving pickup requests, if the status of a given pickup request is available the response will contain a list of all statuses for this pickup request.

E.g. the statusList property might contain:

[
  {
    "status": "WillBePickedUp",
    "timestamp": "2018-06-29T10:30:57.397Z"
  },
  {
    "status": "PickupCompleted",
    "timestamp": "2018-06-29T11:30:57.397Z"
  }
]

If no status is available yet, the statusList will be empty.

Possible status codes
PickupCompleted
PickupDeliveredAtExternalParty
ClosedAddresseeOnVacationOrderCancelled
ClosedOrderCancelled
NoEmptyEuroPalletsPresent
EuroPalletsNotEmptyYet
NothingPickedUpOrderCancelled
NothingPickedUpGoodsAlreadyCollected
NothingPickedUpGoodsAreNotReadyYet
NothingPickedUpNoGoodsForToday
NothingPickedUpNoOrderGiven
NothingPickedUp
BacklogDeliveryOrderCancelled
WillBePickedUp

6.2 Services

6.2.1 Create a pickup request

Service to create a request to come and pick up a parcel by DHL.

Field	Required	Description
accountId	Yes	Customer account id. Depending on country the account id might have a different format.
pickupDate	Yes	Pickup date. Format: yyyy-MM-dd. Must be today + 1, except for Span and Portugal which support Same-Day-Pickup.
description	No	Optional description of what to pickup.
pickupLocation	No	Optional pickup location information.
numberOfPackages	No	Number of packages to pickup. Either numberOfPackages or numberOfPallets must be provided.
numberOfPallets	No	Number of pallets to pickup. Either numberOfPackages or numberOfPallets must be provided.
totalWeight	No	Optional total weight to pickup.
shipper	Yes	Full pickup contact information. See model.
receiver	No	Full receiver contact information. See model. When a value is provided for this field, the pickup driver will bring the associated label.
type	Yes	Only supported value ‘Once’.

6.2.2 Get pickup requests for a user

Retrieves pickup requests created by the user or to which the given user has access. The user id is obtained from the authorization token. If the status of a pickup request is available the response will contain a list of statuses. See Pickup Status for details.

Parameters	Required	Description
limit	true	Maximum number of records to return
skip	true	Number of records to skip (for pagination purposes)
query	false	Optional query for full text search. If provided only pickup requests matching this query will be returned
accountIds	false	Optional list of account ids for which the pickup request should be retrieved. If not provided pickup requests belonging to all accounts to which the user has access will be returned

See API for all supported options.

6.2.3 Get pickup request by id

Retrieves a single pickup request using its id. If the user sending the request is not authorized to access given pickup request or the given pickup request does not exist, not found (404) error code is returned.

If the status of the pickup request is available the response will contain a list of statuses. See Pickup Status for details.

6.3 API Usage

Description	Method	URL
Create a pickup request	POST	https://api-gw.dhlparcel.nl/pickup-requests
Get pickup requests for a user	GET	https://api-gw.dhlparcel.nl/pickup-requests
Get pickup request by id	GET	https://api-gw.dhlparcel.nl/pickup-requests/{id}

6.3.1 Create a pickup request

Request url

https://api-gw-accept.dhlparcel.nl/pickup-requests

Example request

curl -X POST "https://api-gw-accept.dhlparcel.nl/pickup-requests" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJlMTNjZjNlZC1kYTE3LTQxZmQtOTc4Yy05OTdhYWUxYjcwNzkiLCJzdWIiOiIxYzlhMGE2Ni0wMTU4LTRiZjktYTk1Ny1mM2Y1MTQ5NjM0ODUiLCJvcmdhbml6YXRpb25JZCI6IjJlNDEzNGM0LTM1Y2MtNGU5Ni1hMmI4LTFjNjdmNzJkYzI1MSIsIm5iZiI6MTU0MDI5MTkwMywiZXhwIjoxNTQwMjkyODA0LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.RV2rU7Qjj25x_l-aoqNby9vt8VxQYYyo8IzU8d7nEs8" -H "content-type: application/json" -d "{ \"accountId\": \"08500001\", \"pickupDate\": \"2018-10-24\", \"numberOfPackages\": 1, \"shipper\": { \"name\": { \"firstName\": \"string\", \"lastName\": \"string\", \"companyName\": \"string\", \"additionalName\": \"string\" }, \"email\": { \"address\": \"string\" }, \"phoneNumber\": \"string\", \"address\": { \"countryCode\": \"NL\", \"postalCode\": \"1000AA\", \"city\": \"Amsterdam\", \"street\": \"Kalverstraat\", \"number\": \"10\", \"addition\": \"B\", \"isBusiness\": true, \"additionalInfo\": \"2nd Floor, 1st door on right.\" } }, \"receiver\": { \"name\": { \"firstName\": \"string\", \"lastName\": \"string\", \"companyName\": \"string\", \"additionalName\": \"string\" }, \"email\": { \"address\": \"string\" }, \"phoneNumber\": \"string\", \"address\": { \"countryCode\": \"NL\", \"postalCode\": \"1000AA\", \"city\": \"Amsterdam\", \"street\": \"Kalverstraat\", \"number\": \"10\", \"addition\": \"B\", \"isBusiness\": true, \"additionalInfo\": \"2nd Floor, 1st door on right.\" } }, \"timeSlot\": { \"from\": \"10:15\", \"to\": \"16:30\" }, \"type\": \"Once\", \"provideLabels\": false}"

Responses

Success (code 201)

{
  "id": "ed22518d-35f1-4fd9-a7fd-988d8436eb27",
  "userId": "1c9a0a66-0158-4bf9-a957-f3f514963485",
  "accountId": "08500001",
  "pickupDate": "2018-10-24",
  "numberOfPackages": 1,
  "shipper": {
    "name": {
      "firstName": "string",
      "lastName": "string",
      "companyName": "string",
      "additionalName": "string"
    },
    "email": {
      "address": "string"
    },
    "phoneNumber": "string",
    "address": {
      "countryCode": "NL",
      "postalCode": "1000AA",
      "city": "Amsterdam",
      "street": "Kalverstraat",
      "number": "10",
      "addition": "B",
      "isBusiness": true,
      "additionalInfo": "2nd Floor, 1st door on right."
    }
  },
  "receiver": {
    "name": {
      "firstName": "string",
      "lastName": "string",
      "companyName": "string",
      "additionalName": "string"
    },
    "email": {
      "address": "string"
    },
    "phoneNumber": "string",
    "address": {
      "countryCode": "NL",
      "postalCode": "1000AA",
      "city": "Amsterdam",
      "street": "Kalverstraat",
      "number": "10",
      "addition": "B",
      "isBusiness": true,
      "additionalInfo": "2nd Floor, 1st door on right."
    }
  },
  "confirmationNumber": "4031173P",
  "statusList": []
}

6.3.2 Get pickup requests for a user

Request url

Minimal request:
https://api-gw-accept.dhlparcel.nl/pickup-requests?limit={limit}&skip={skip}

With query and/or account ids:
https://api-gw-accept.dhlparcel.nl/pickup-requests?limit={limit}&skip={skip}&accountIds={accountId1}&accountIds={accountId2}&query={optionalQuery}

Example request

curl -X GET "https://api-gw-accept.dhlparcel.nl/pickup-requests?limit=5&skip=2" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJlMTNjZjNlZC1kYTE3LTQxZmQtOTc4Yy05OTdhYWUxYjcwNzkiLCJzdWIiOiIxYzlhMGE2Ni0wMTU4LTRiZjktYTk1Ny1mM2Y1MTQ5NjM0ODUiLCJvcmdhbml6YXRpb25JZCI6IjJlNDEzNGM0LTM1Y2MtNGU5Ni1hMmI4LTFjNjdmNzJkYzI1MSIsIm5iZiI6MTU0MDI5MTkwMywiZXhwIjoxNTQwMjkyODA0LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.RV2rU7Qjj25x_l-aoqNby9vt8VxQYYyo8IzU8d7nEs8"

Responses

Success (code 200)

{
  "results": 14,
  "limit": 5,
  "skip": 2,
  "data": [
    {
      "id": "ed22518d-35f1-4fd9-a7fd-988d8436eb27",
      "userId": "1c9a0a66-0158-4bf9-a957-f3f514963485",
      "timeCreated": "2018-10-23T10:54:01.843Z",
      "accountId": "08500001",
      "pickupDate": "2018-10-24",
      "numberOfPackages": 1,
      "numberOfPallets": 0,
      "shipper": {
        "name": {
          "firstName": "string",
          "lastName": "string",
          "companyName": "string",
          "additionalName": "string"
        },
        "email": {
          "address": "string"
        },
        "phoneNumber": "string",
        "address": {
          "countryCode": "NL",
          "postalCode": "1000AA",
          "city": "Amsterdam",
          "street": "Kalverstraat",
          "number": "10",
          "addition": "B",
          "isBusiness": true,
          "additionalInfo": "2nd Floor, 1st door on right."
        }
      },
      "receiver": {
        "name": {
          "firstName": "string",
          "lastName": "string",
          "companyName": "string",
          "additionalName": "string"
        },
        "email": {
          "address": "string"
        },
        "phoneNumber": "string",
        "address": {
          "countryCode": "NL",
          "postalCode": "1000AA",
          "city": "Amsterdam",
          "street": "Kalverstraat",
          "number": "10",
          "addition": "B",
          "isBusiness": true,
          "additionalInfo": "2nd Floor, 1st door on right."
        }
      },
      "confirmationNumber": "4031173P",
      "statusList": []
    },
    ...
  ]
}

6.3.3 Get a pickup request by id

Request url

https://api-gw-accept.dhlparcel.nl/pickup-requests/{id}

Example request

curl -X GET "https://api-gw-accept.dhlparcel.nl/pickup-requests/b9b0c8d9-153d-4f59-815b-94759ccf1ddf" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJlMTNjZjNlZC1kYTE3LTQxZmQtOTc4Yy05OTdhYWUxYjcwNzkiLCJzdWIiOiIxYzlhMGE2Ni0wMTU4LTRiZjktYTk1Ny1mM2Y1MTQ5NjM0ODUiLCJvcmdhbml6YXRpb25JZCI6IjJlNDEzNGM0LTM1Y2MtNGU5Ni1hMmI4LTFjNjdmNzJkYzI1MSIsIm5iZiI6MTU0MDI5MTkwMywiZXhwIjoxNTQwMjkyODA0LCJyb2xlcyI6WyJsYWJlbC1zZXJ2aWNlLkIyWCIsInBpY2t1cC1zZXJ2aWNlLkIyWCJdLCJhY2NvdW50cyI6WyIwODUwMDAwMSJdfQ.RV2rU7Qjj25x_l-aoqNby9vt8VxQYYyo8IzU8d7nEs8"

Responses

Success (code 200)

{
   "id":"b615a70c-d320-4517-8710-983e45dbb52b",
   "userId":"f57117a6-b088-4cee-82bf-c8b561d704a6",
   "timeCreated":"2018-10-24T08:45:08.154Z",
   "accountId":"08500001",
   "pickupDate":"2018-11-02",
   "description":"Office no 1",
   "numberOfPackages":2,
   "numberOfPallets":0,
   "shipper":{
      "name":{
         "firstName":"John",
         "lastName":"Doe",
         "companyName":"JDC"
      },
      "email":{
         "address":"[email protected]"
      },
      "phoneNumber":"+31611111111",
      "address":{
         "countryCode":"NL",
         "postalCode":"3542AD",
         "city":"Utrecht",
         "street":"Reactorweg",
         "number":"30",
         "isBusiness":true
      }
   },
   "confirmationNumber":"4031175P",
   "statusList":[]
}

6.4 Testing

These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test cases which are suitable for your line of business or wishes.

Suggested Test Cases	Expected Result
Create a pickup request	A new pickup request is created and returned.
Get pickup request. Try different scenario’s with pagination.	Pickup requests for a user, organization or account id depending on the test case.