Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pickups

Retrieve list of courier pickup requests

get
/pickups

This method allows business clients to retrieve a list of all courier pickup requests they have created. Clients can filter the list using specific parameters such as pickup IDs or pickup numbers.

CourierPickupService: This service allows business clients to request a paid courier pickup without pre-creating shipments.

Behavior: A pickup request using the CourierPickupService service can reach the Created status without any associated shipments. Shipments can be added later after the pickup request is created.

Permissions: This service is restricted and available only for authorized business accounts according to individual contract terms. The service is currently available in Moldova.

If the service is not available in your account, please contact your Nova Post account manager or Sales representative.

This method is available to business clients in EU countries where Nova Post operates.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
numbers[]stringOptional

Search pickups by document number. Can accept either a single search number or an array of numbers for conducting the search.

Example: PUCZ0000002671
ids[]integer · int32Optional

A list of pickup request IDs to search. Can accept either a single search number or an array of numbers for conducting the search.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup request by its document number.

Example: 296132
serviceCodes[]stringOptional

Filter pickup requests by service code.

Allowed values:

  • CourierPickupService

Returns only pickup requests that contain the specified service.

Example: CourierPickupService
limitinteger · int32Optional

Max number of items to return on page.

Default: 15Example: 1
pageinteger · int32Optional

Number of page to return.

Example: 1
Body
idsstring · max: 296132Optional

A list of pickup request IDs to search.

Responses
200

List of courier pickup requests retrieved successfully.

application/json
current_pageinteger · min: 1Optional

The current page of results in the paginated response.

last_pageinteger · min: 1Optional

The last available page in the paginated response.

per_pageinteger · min: 1Optional

The number of items per page.

totalintegerOptional

Total number of pickup requests matching the filter criteria.

get/pickups
GET /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "ids": [
    296132
  ]
}
{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1,
  "items": [
    {
      "id": "28813",
      "number": "PUPL0000013342",
      "versionTracking": null,
      "status": "Draft",
      "statusDateTime": "2024-12-20T09:01:56.927000Z",
      "createdAt": "2024-12-20T09:01:56.928000Z",
      "updatedAt": "2024-12-20T11:58:08.731000Z",
      "deletedAt": null,
      "lastPublishedAt": "2024-12-20T11:58:08.000000Z",
      "lastUpdatedAt": "2024-12-20T11:58:08.831311Z",
      "source": "clientapi",
      "executor": null,
      "companyTin": "",
      "companyName": null,
      "fullName": "Chulkov Ihor",
      "phone": "380001234567",
      "email": "i.s.chulkov@gmail.com",
      "country": "Poland",
      "countryCode": "PL",
      "createdByUser": "84dbbfac-3508-11ee-a361-48df37b92096",
      "deliveryPartner": null,
      "lockVersion": 2,
      "divisionId": null,
      "settlementId": 22326,
      "settlementExternalId": null,
      "settlementName": "Warsaw",
      "cityDistrict": null,
      "cityDistrictExternalId": null,
      "address": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "",
        "address": "17890, Polska, Województwo mazowieckie, Warszawa County, Warszawa, 15 Sierpnia, 1, , , ",
        "addressId": null,
        "latitude": 52.3264159,
        "longitude": 20.9854961,
        "timeZoneId": 367,
        "timeZone": "Europe/Warsaw"
      },
      "addressParts": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "Information about building entrance for courier access"
      },
      "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
      "pickedTimeTo": "2024-12-01T18:00:00.000000Z",
      "note": "Test pickup request",
      "currencyCode": "CZK",
      "shipments": [],
      "services": [
        {
          "id": 1040,
          "shipmentParcelRowNumber": "",
          "serviceId": "12292132641000939",
          "pickupId": 604431,
          "serviceType": "PickUpManual",
          "serviceName": "",
          "serviceCode": "CourierPickupService",
          "parcelNumber": "",
          "payerType": "Sender",
          "contractNumber": "string",
          "amount": 150,
          "price": 250,
          "discount": 0,
          "cost": 250,
          "costBeforeCheck": false,
          "paymentStatus": "ContractAfterPayment",
          "currencyCode": "MDL",
          "executionAt": "2026-06-16T10:20:42.564463Z",
          "additionalParameters": {
            "parcel_description": "string",
            "parcels_amount": 10,
            "total_actual_weight": 0,
            "total_volumetric_weight": 0,
            "length": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "statuses": [
        {
          "id": 109777,
          "pickupId": 28813,
          "status": "Draft",
          "dateTime": "2024-12-01T13:55:57.350277Z",
          "note": null,
          "user": "d389d1ec-2078-4b62-8bc0-696c72a52a65",
          "createdAt": "2025-01-22T07:58:52.388849Z",
          "updatedAt": "2025-01-22T07:58:52.388849Z",
          "deletedAt": null
        }
      ]
    }
  ]
}

Retrieve available pickup time intervals

post
/time-intervals/find

This method retrieves available time intervals for pickups. The algorithm operates based on geographical zones serviced by couriers. These zones are conditional areas on a map defined by logistical features of courier operations. Depending on the pickup location, the system identifies the specific courier responsible for that zone and returns the detailed time intervals available for pickup.

Mandatory Parameters:

  • countryCode: Specifies the country code according to ISO 3166-1 Alpha-2 standard.

  • type: Defines the type of pickup. Allowed values are PickupDayToDay (same-day pickup) or PickupNextDay (next-day pickup).

If only these two parameters are provided, the method will return general courier working hours for the specified country without detailed intervals for a specific location or zone.

Recommended Parameters for Accurate Results:

  • addressParts: Provide the full pickup address, including building, street, city, region, and postal code. This ensures precise time intervals are returned for the specified address.

  • latitude and longitude: Use geographical coordinates if a full address is not available to determine the zone.

  • divisionId: Specify the ID of the nearest division if the exact address is unknown. However, note that proximity to a division does not guarantee that the courier servicing the address operates from the same division.

Additional Parameters:

  • weight: Time intervals may depend on the shipment's weight. This parameter is helpful for large or weight-sensitive shipments.

Important Notes:

  1. If only countryCode and type are provided, the system will return general working hours of couriers without detailed time intervals for a specific address.

  2. For the most accurate time intervals, providing a full address or coordinates is strongly recommended.

Time Interval Selection Logic:

  • If a PickupDayToDay configuration exists:

    • It takes priority over PickupNextDay.

    • Today is available if:

      • Not a holiday (holiday == false);

      • A working schedule exists (from != null);

      • Current time < orderTo.

    • Up to 7 calendar days (including today) may be returned if:

      • Not holidays;

      • from is set;

      • orderTo is only checked for today.

  • If no PickupDayToDay, but PickupNextDay is configured:

    • Today is not available.

    • Up to 7 calendar days (excluding today) may be returned if:

      • Not holidays;

      • from is set.

    • orderTo applies only to tomorrow. If current time > orderTo, tomorrow is excluded.

  • If no time interval configuration exists (fallback mode):

    • Today is not available.

    • Up to 7 calendar days (excluding today, weekends, holidays) may be returned.

    • A fixed orderTo = 17:00 applies only to tomorrow.

Note: If from is set but timeIntervals is empty, the courier will arrive sometime during the day without a fixed slot. This logic applies to all types of configurations.

Validation behavior:

  • If the selected day is no longer valid, the system automatically assigns the next available valid day.

  • If the time interval is invalid or empty, the courier will arrive during the full working period.

Recommendation: Providing full address details or coordinates is strongly recommended to ensure accurate time interval results.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
typestring · enumRequired

Type of time interval. Allowed values are PickupDayToDay or PickupNextDay.

Possible values:
countryCodestringRequired

Country code according to the ISO 3166-1 Alpha-2 standard.

Pattern: ^[A-Z]{2}$
divisionIdinteger · min: 1 · nullableOptional

Division ID for specific branch identification.

latitudenumber · min: -90 · max: 90 · nullableOptional

Latitude for geolocation-based search.

longitudenumber · min: -180 · max: 180 · nullableOptional

Longitude for geolocation-based search.

maxWeightPlaceRecipientinteger · nullableOptional

Weight of the shipment in kilograms. Optional for non-weight-sensitive intervals.

Responses
200

Time intervals retrieved successfully.

application/json
idinteger · min: 1Optional

Unique identifier for the time interval.

countryCodestringOptional

Country code according to the ISO 3166-1 Alpha-2 standard.

Pattern: ^[A-Z]{2}$
divisionIdinteger · min: 1 · nullableOptional

Division ID related to the time interval.

typestring · enumOptional

The type of the time interval.

Possible values:
deliveryPartnerstring · nullableOptional

Partner responsible for the pickup, if applicable.

ignoreNonWorkingDaysbooleanOptional

Whether to include non-working days in the search.

createdAtstring · date-timeOptional

The date-time indicating when the record was initially created.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
updatedAtstring · date-timeOptional

The date-time indicating when the record was last updated.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
deletedAtstring · date-time · nullableOptional

The date-time indicating when the record was deleted.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
post/time-intervals/find
POST /v.1.0/time-intervals/find HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 264

{
  "type": "PickupNextDay",
  "countryCode": "CZ",
  "latitude": 50.0755,
  "longitude": 14.4378,
  "maxWeightPlaceRecipient": 5,
  "addressParts": {
    "building": "30",
    "street": "Václavské náměstí",
    "city": "Prague",
    "region": "Central Bohemia",
    "postCode": "11000",
    "note": "Near the statue"
  }
}
{
  "id": 1,
  "countryCode": "CZ",
  "divisionId": null,
  "type": "PickupNextDay",
  "deliveryPartner": null,
  "ignoreNonWorkingDays": false,
  "monday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "tuesday": {
    "from": "08:00",
    "to": "20:00",
    "orderTo": "19:30",
    "timeIntervals": [
      {
        "from": "08:00",
        "to": "12:00",
        "orderTo": "11:30"
      },
      {
        "from": "13:00",
        "to": "20:00",
        "orderTo": "19:30"
      }
    ]
  },
  "wednesday": {
    "from": "08:00",
    "to": "20:00",
    "orderTo": "19:00",
    "timeIntervals": []
  },
  "thursday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "friday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "saturday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "sunday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "createdAt": "2024-12-01T13:55:57.350861Z",
  "updatedAt": "2024-12-01T13:55:57.350861Z",
  "deletedAt": null
}

Create a courier pickup request

post
/pickups

This method allows business clients to create a new courier pickup request by specifying essential parameters such as the pickup address, parcel type, and additional details.

Initial Status (Draft): The pickup request is created in the Draft status, which allows clients to add all necessary shipments to the request.

Transition to Created: Once all shipments are added, clients must use the "Update pickup request status" method to change the status to Created. This indicates that the pickup is finalized and ready for processing by the courier service.

Time Intervals: To include a specific time interval for the pickup, clients should retrieve available time intervals using the corresponding method. This ensures that the requested pickup time aligns with the courier's schedule and availability.

Additional Service – CourierPickupService: Clients can optionally provide information about the planned cargo in the services array using the CourierPickupService service. This allows the client to specify estimated shipment characteristics such as parcel description, quantity, actual and volumetric weight, and optional dimensions. The service is currently available in Moldova. The information is used during pickup planning and courier processing.

This method is available to business clients in EU countries where Nova Post operates.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesarray · nullableOptional

List of additional services associated with the pickup request.

Currently supported service:

  • CourierPickupService — allows the client to provide planned cargo information that will be used during pickup planning and courier processing.
phonestring · min: 8 · max: 14Optional

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Optional

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

countryCodestringOptional

ISO Alpha-2 code for the pickup location.

Pattern: ^[A-Z]{2}$
pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
Responses
201

Pickup request created successfully

application/json
idinteger · min: 1Optional

Unique identifier for the pickup request.

numberstringOptional

Reference number for the pickup request.

Pattern: ^[A-Z]{4}\d{10}$
statusstringOptional

Current pickup status, representing the different stages in the pickup process.

Possible values include:

  • Draft: Initial stage where the pickup request is created but not yet finalized.
  • Created: The pickup request has been created and is ready for processing.
  • AppointedCourier: A courier has been assigned to the pickup request.
  • InProgress: The pickup process is underway.
  • Done: The pickup has been successfully completed.
  • ClientCanceled: The pickup was canceled by the client.
  • NotCompleted: The pickup process could not be completed.
  • Deleted: The pickup request has been removed from the system.
  • ReceivedByCourier: The parcel has been received by the courier.
statusDateTimestring · date-timeOptional

Date and time when the status was last updated.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
sourcestring · max: 50Optional

Origin of the request, typically "clientapi".

executorstring · max: 50 · nullableOptional

Assigned executor for the pickup, if any.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company.

fullNamestring · max: 100Optional

Full name of the requester.

phonestring · min: 8 · max: 14Optional

Contact phone number.

emailstring · nullableOptional

Contact email address, if applicable.

countryCodestringOptional

Country code for the pickup location.

Pattern: ^[A-Z]{2}$
createdByUserstring · max: 50Optional

ID of the user who created the request.

deliveryPartnerstring · nullableOptional

Partner responsible for delivery, if any.

lockVersioninteger · min: 1Optional

Version number for concurrency control.

divisionIdinteger · min: 1 · nullableOptional

Division ID associated with the pickup, if applicable.

settlementIdinteger · min: 1Optional

Settlement ID for the pickup location.

cityDistrictstring · max: 50 · nullableOptional

City district of the pickup location, if applicable.

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, specified in request.

pickedTimeTostring · date-time · nullableOptional

End time for the pickup window, specified in request.

notestring · max: 255 · nullableOptional

Note or instructions for the courier.

currencyCodestringOptional

Currency code of the country used for payment transactions.

Pattern: ^[A-Z]{3}$
externalIdstring · nullableOptional

Internal data, not for use.

shipmentsobject[]Optional

List of shipments associated with this pickup request.

createdAtstring · date-timeOptional

Date-time of pickup creation.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
updatedAtstring · date-timeOptional

Date-time of the last update.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
deletedAtstring · date-time · nullableOptional

Date-time of delete.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
post/pickups
POST /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 449

{
  "note": "Test pickup 777",
  "services": [],
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "fullName": "Chuck Norris",
  "companyTin": "",
  "companyName": "",
  "countryCode": "PL",
  "addressParts": {
    "city": "Warszawa",
    "region": "Warszawa County",
    "street": "Admiralska",
    "postCode": "01234",
    "building": "1",
    "flat": "1",
    "block": "",
    "note": "Test shipment, do not process"
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z"
}
{
  "id": 296132,
  "number": "PUPL7092967496",
  "status": "Draft",
  "statusDateTime": null,
  "source": "clientapi",
  "executor": null,
  "companyTin": "",
  "companyName": "",
  "fullName": "Chuck Norris",
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "countryCode": "PL",
  "createdByUser": "acab5818-0944-5595-b30c-b788ae280f61",
  "deliveryPartner": null,
  "lockVersion": 1,
  "divisionId": null,
  "settlementId": 22326,
  "cityDistrict": null,
  "address": {
    "string": "01234, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Admiralska, 1, , 1, Test shipment, do not process",
    "latitude": 52.26215209999999,
    "longitude": 21.1792149
  },
  "addressParts": {
    "postCode": "01234",
    "building": "1",
    "street": "Admiralska",
    "city": "Warszawa",
    "region": "Warszawa County",
    "flat": "1",
    "note": "Test shipment, do not process",
    "block": ""
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z",
  "note": "Test pickup 777? Тестовий пікап, не обробляйте!",
  "currencyCode": "PLN",
  "externalId": null,
  "shipments": [],
  "services": [],
  "statuses": [
    {
      "id": 634036,
      "pickupId": 296132,
      "status": "Draft",
      "dateTime": "2025-12-11T10:36:28.551560Z",
      "note": null,
      "user": "acab5818-0944-4395-b30c-b788ae280f61",
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:36:28.552814Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2025-12-11T10:36:28.552814Z",
  "updatedAt": "2025-12-11T10:36:28.552814Z",
  "deletedAt": null
}

Update a courier pickup request

put
/pickups/{id}

The method is used to update the details of an already created pickup request. It allows clients to modify information such as the pickup address, contact details, time window and other to ensure accurate and timely parcel collection. This method is available to business clients in EU countries where Nova Post operates.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

Unique identifier of the pickup request to be updated.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Body
notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesstring[] · nullableOptional

List of additional services that can be included in the pickup request. This functionality is currently under development.

phonestring · min: 8 · max: 14Optional

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Optional

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

lockVersioninteger · min: 1Optional

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

countryCodestringOptional

ISO Alpha-2 code for the pickup location.

Pattern: ^[A-Z]{2}$
pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
Responses
200

Pickup request updated successfully.

application/json
idinteger · min: 1Optional

Unique identifier for the updated pickup request.

numberstringOptional

Reference number for the pickup request.

Pattern: ^[A-Z]{4}\d{10}$
statusstringOptional

Current pickup status, representing the different stages in the pickup process.

Possible values include:

  • Draft: Initial stage where the pickup request is created but not yet finalized.
  • Created: The pickup request has been created and is ready for processing.
  • AppointedCourier: A courier has been assigned to the pickup request.
  • InProgress: The pickup process is underway.
  • Done: The pickup has been successfully completed.
  • ClientCanceled: The pickup was canceled by the client.
  • NotCompleted: The pickup process could not be completed.
  • Deleted: The pickup request has been removed from the system.
  • ReceivedByCourier: The parcel has been received by the courier.
lockVersionintegerOptional

Updated version number for concurrency control.

notestring · max: 255Optional

Updated notes for the courier.

pickedTimeFromstring · date-timeOptional

Updated start of the pickup time window.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-timeOptional

Updated end of the pickup time window.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
statusesobject[]Optional

Array of updated status objects tracking pickup status changes.

put/pickups/{id}
PUT /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 500

{
  "note": "Update note for the pickup",
  "services": [],
  "phone": "420123456789",
  "email": "test@example.cz",
  "fullName": "Updated Test User",
  "companyTin": "CZ98765432",
  "companyName": "Updated Test Company CZ",
  "lockVersion": 2,
  "countryCode": "CZ",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z"
}
{
  "id": 28813,
  "number": "PUCZ0000002671",
  "status": "Draft",
  "lockVersion": 2,
  "note": "Na Rizdvo Sobi",
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "statuses": [
    {
      "id": 109777,
      "status": "Draft",
      "dateTime": "2024-11-13T18:52:57.350277Z",
      "createdAt": "2024-11-13T18:52:57.350861Z",
      "updatedAt": "2024-12-02T14:10:00.000000Z"
    }
  ]
}

Delete a courier pickup request

delete
/pickups/{id}

This method allows business clients to fully delete an existing courier pickup request. When a pickup request is deleted, it is marked as removed in the system, and the deletion date-time is recorded. This method is available to business clients in EU countries where Nova Post operates.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

Unique identifier of the pickup request to be deleted.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Responses
200

Pickup request deleted successfully.

application/json
deletedAtstring · date-timeOptional

The date-time when the pickup request was marked as deleted.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
delete/pickups/{id}
DELETE /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "deletedAt": "2024-11-13T20:29:47.285749Z"
}

Add shipments to a courier pickup request

post
/pickups/{id}/shipments

This method is used to add already created shipments to an existing courier pickup request. According to the established business process, already created shipments must be added to the courier pickup request after it has been created. This method is available to business clients in EU countries where Nova Post operates.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

Unique identifier of the pickup request to which shipments are being added.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Body
Responses
200

Shipments successfully added to the pickup request.

application/json
post/pickups/{id}/shipments
POST /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "shipments": [
    {
      "shipmentId": 1517240
    },
    {
      "shipmentId": 1517330
    }
  ]
}
{
  "shipments": [
    {
      "id": 189608,
      "pickupId": 296132,
      "shipmentId": 1517240,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    },
    {
      "id": 189609,
      "pickupId": 296132,
      "shipmentId": 1517330,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    }
  ]
}

Remove shipments from a pickup request

delete
/pickups/{id}/shipments

This endpoint allows removing specific shipments from an existing courier pickup request.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

The unique identifier of the pickup request.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Body
Responses
200

Shipments removed successfully

application/json
delete/pickups/{id}/shipments
DELETE /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "shipments": [
    {
      "shipmentId": 370681
    }
  ]
}
{
  "shipments": [
    {
      "deletedAt": "2024-11-13T20:22:56.818679Z"
    }
  ]
}

Update pickup request status

put
/pickups/{id}/status

This method allows updating the status of an existing courier pickup request. It is specifically designed for transitioning a pickup request from Draft to Created.

While the request is in Draft status, it remains in a preparatory phase where all necessary shipments can be added. Once the status is updated to Created, the shipment management system recognizes the pickup as finalized and ready for processing by the courier service.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

The unique identifier of the pickup request.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Body
statusstring · enumRequired

This field is used to update the status of a pickup request to indicate that the pickup request is finalized and ready for processing by the shipment management system.

Possible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.

Possible values:
lockVersioninteger · min: 1Required

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

notestring · max: 255Optional

A required note or comment providing additional information about the reason for the status update. This field must be filled when changing the status to ensure proper tracking and context.

Responses
200

Status updated successfully

application/json
successbooleanOptional

Indicates whether the status update was successful.

put/pickups/{id}/status
PUT /v.1.0/pickups/{id}/status HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "status": "Created",
  "lockVersion": 2,
  "note": "Test changhe status to Created!"
}
{
  "success": true
}
PreviousRegisters
NextWebhooks

Last updated