--- title: "Retrieve list of courier pickup requests" method: GET path: "/pickups" tags: ["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. ## Query parameters - `numbers[]` string - `ids[]` integer - `serviceCodes[]` string - `limit` integer - `page` integer ## Request body - object - `ids` string — A list of pickup request IDs to search. ## Response `200` List of courier pickup requests retrieved successfully. - object - `current_page` integer — The current page of results in the paginated response. - `last_page` integer — The last available page in the paginated response. - `per_page` integer — The number of items per page. - `total` integer — Total number of pickup requests matching the filter criteria. - `items` object[] — List of pickup requests. - `id` string — Unique identifier for the pickup request. - `number` string — Reference number for the pickup request. - `status` string — 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. - `statusDateTime` string, date-time — Date-time of the last status update. - `source` string — Source of the request creation (e.g., API, Web). - `executor` string — Identifier of the executor (courier or service). - `companyTin` string — The tax identification number (TIN) of a legal entity. - `companyName` string — Name of the company creating the request. - `fullName` string — Full name of the client sending the parcel. - `phone` string — The contact phone number of the sender. - `email` string, nullable — Contact email address, if applicable. - `countryCode` string — ISO Alpha-2 code for the pickup location. - `externalId` string — External identifier of the pickup request provided by the client. - `createdByUser` string — User ID of the person who created the request. - `divisionId` integer — Division ID responsible for handling the request. - `settlementId` integer — Settlement ID for the pickup location. - `cityDistrict` string — District of the city for the pickup. - `deliveryPartner` string — Delivery partner handling the request. - `lockVersion` integer — Version control number for preventing conflicts during updates. - `address` object — Full address details. - `address` string — Full formatted address. - `latitude` string — Latitude coordinate of the pickup location. - `longitude` string — Longitude coordinate of the pickup location. - `timeZoneId` integer — Time Zone internal identificator. - `timeZone` string — Time Zone of the pickup location based on latitude and longitude. - `addressParts` object — Breakdown of address details. - `postCode` string — Postal code of the pickup location. - `building` string — Building number of the pickup location. - `street` string — Street name for the pickup location. - `city` string — City name for the pickup location. - `region` string — Region name for the pickup location. - `flat` string — Flat or apartment number. - `note` string — Additional notes for the address. - `block` string, nullable — Block or building section. - `pickedTimeFrom` string, date-time, nullable — Start of the pickup time window, specified in request. - `pickedTimeTo` string, date-time, nullable — End time for the pickup window, specified in request. - `currencyCode` string — Currency code of the country used for payment transactions. - `shipments` object[] — List of shipments associated with this pickup request. - `services` object[] — List of additional services associated with the pickup request. - `id` integer — Unique service identifier. - `shipmentParcelRowNumber` string, nullable — Parcel row number associated with the service. - `serviceId` string — Internal service identifier. - `pickupId` integer — Pickup request identifier. - `serviceType` string — Internal service type. - `serviceName` string, nullable — Service name. - `serviceCode` string — Service code. - `parcelNumber` string, nullable — Associated parcel number. - `payerType` string — Party responsible for payment. - `contractNumber` string — Contract number used for service payment. - `amount` number — Service amount. - `price` number — Service price before discounts. - `discount` number — Applied discount amount. - `cost` number — Final service cost. - `costBeforeCheck` boolean — Indicates whether the cost was calculated before validation. - `paymentStatus` string — Current payment status. - `currencyCode` string — ISO 4217 currency code. - `executionAt` string, date-time — Date and time of service execution. - `additionalParameters` object — Planned cargo parameters provided for the CourierPickupService. - `parcel_description` string — Description of the cargo. - `parcels_amount` number — Planned number of parcels. - `total_actual_weight` number — Total planned actual weight. - `total_volumetric_weight` number — Total planned volumetric weight. - `length` number — Planned parcel length. - `width` number — Planned parcel width. - `height` number — Planned parcel height. - `statuses` object[] — Array of status objects tracking pickup status changes. - `id` integer — Unique status identifier. - `pickupId` integer — Pickup request ID. - `status` string — Current pickup status, representing the different stages in the pickup process. Possible values include: `Draft`, `Created`, `AppointedCourier`, `InProgress`, `Done`, `ClientCanceled`, `NotCompleted`, `Deleted`, `ReceivedByCourier`. - `dateTime` string, date-time — Date and time of status update. - `note` string, nullable — Optional notes related to the status. - `user` string — User ID who changed the status. - `createdAt` string, date-time — Date-time of status creation. - `updatedAt` string, date-time — Date-time of the last update. - `deletedAt` string, date-time, nullable — Date-time of delete, if applicable. - `createdAt` string, date-time — Date-time when the pickup request was created. - `updatedAt` string, date-time — Date-time when the pickup request was last updated. - `deletedAt` string, date-time, nullable — Date-time when the pickup request was deleted, if applicable. ## Other responses - `401` — Unauthorized - `404` — The specified resource was not found - `422` — Validation error - `503` — Connection time-out --- [API](https://skmtc.net/novapost/apis/api-nova-post.md) · [All operations](https://skmtc.net/novapost/apis/api-nova-post/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novapost/api-nova-post/revisions/60e380005037/schema)