# Pickups ## Retrieve list of courier pickup requests > 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.\ > This method is available to business clients in EU countries where Nova Post operates.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups":{"get":{"tags":["Pickups"],"description":"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.\nThis method is available to business clients in EU countries where Nova Post operates.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","parameters":[{"in":"query","name":"numbers[]","description":"Search pickups by document number. Can accept either a single search number or an array of numbers for conducting the search.","schema":{"type":"string"}},{"in":"query","name":"ids[]","description":"A list of pickup request IDs to search. Can accept either a single search number or an array of numbers for conducting the search.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"limit","description":"Max number of items to return on page.","schema":{"type":"integer","format":"int32","default":15}},{"in":"query","name":"page","description":"Number of page to return.","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"List of courier pickup requests retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"The current page of results in the paginated response.","minimum":1},"last_page":{"type":"integer","description":"The last available page in the paginated response.","minimum":1},"per_page":{"type":"integer","description":"The number of items per page.","minimum":1},"total":{"type":"integer","description":"Total number of pickup requests matching the filter criteria.","minimum":0},"items":{"type":"array","description":"List of pickup requests.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the pickup request.","minimum":1},"number":{"type":"string","description":"Reference number for the pickup request.","pattern":"^[A-Z]{4}\\d{10}$"},"status":{"type":"string","description":"Current pickup status, representing the different stages in the pickup process.\nPossible values include:\n - Draft: Initial stage where the pickup request is created but not yet finalized.\n - Created: The pickup request has been created and is ready for processing.\n - AppointedCourier: A courier has been assigned to the pickup request.\n - InProgress: The pickup process is underway.\n - Done: The pickup has been successfully completed.\n - ClientCanceled: The pickup was canceled by the client.\n - NotCompleted: The pickup process could not be completed.\n - Deleted: The pickup request has been removed from the system.\n - ReceivedByCourier: The parcel has been received by the courier.\n"},"statusDateTime":{"type":"string","format":"date-time","description":"Date-time of the last status 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$"},"source":{"type":"string","description":"Source of the request creation (e.g., API, Web)."},"executor":{"type":"string","description":"Identifier of the executor (courier or service)."},"companyTin":{"type":"string","description":"The tax identification number (TIN) of a legal entity."},"companyName":{"type":"string","description":"Name of the company creating the request."},"fullName":{"type":"string","description":"Full name of the client sending the parcel.","maxLength":100},"phone":{"type":"string","description":"The contact phone number of the sender.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Contact email address, if applicable.","nullable":true},"countryCode":{"type":"string","description":"ISO Alpha-2 code for the pickup location.","pattern":"^[A-Z]{2}$"},"externalId":{"type":"string","description":"External identifier of the pickup request provided by the client."},"createdByUser":{"type":"string","description":"User ID of the person who created the request."},"divisionId":{"type":"integer","description":"Division ID responsible for handling the request."},"settlementId":{"type":"integer","description":"Settlement ID for the pickup location."},"cityDistrict":{"type":"string","description":"District of the city for the pickup."},"deliveryPartner":{"type":"string","description":"Delivery partner handling the request."},"lockVersion":{"type":"integer","description":"Version control number for preventing conflicts during updates."},"address":{"type":"object","description":"Full address details.","properties":{"address":{"type":"string","description":"Full formatted address."},"latitude":{"type":"string","description":"Latitude coordinate of the pickup location."},"longitude":{"type":"string","description":"Longitude coordinate of the pickup location."}}},"addressParts":{"type":"object","description":"Breakdown of address details.","properties":{"postCode":{"type":"string","description":"Postal code of the pickup location.","maxLength":10},"building":{"type":"string","description":"Building number of the pickup location.","maxLength":100},"street":{"type":"string","description":"Street name for the pickup location.","maxLength":100},"city":{"type":"string","description":"City name for the pickup location.","maxLength":100},"region":{"type":"string","description":"Region name for the pickup location.","maxLength":100},"flat":{"type":"string","description":"Flat or apartment number.","maxLength":10},"note":{"type":"string","description":"Additional notes for the address.","maxLength":100},"block":{"type":"string","description":"Block or building section.","maxLength":100,"nullable":true}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Start of the pickup time window, specified in request.","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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"End time for the pickup window, specified in request.","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$","nullable":true},"currencyCode":{"type":"string","description":"Currency code of the country used for payment transactions.","pattern":"^[A-Z]{3}$"},"shipments":{"type":"array","items":{"type":"object"},"description":"List of shipments associated with this pickup request."},"services":{"type":"array","items":{"type":"object"},"description":"List of additional services requested."},"statuses":{"type":"array","description":"Array of status objects tracking pickup status changes.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique status identifier.","minimum":1},"pickupId":{"type":"integer","description":"Pickup request ID.","minimum":1},"status":{"type":"string","description":"Current pickup status, representing the different stages in the pickup process.\nPossible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.\n"},"dateTime":{"type":"string","format":"date-time","description":"Date and time of status 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$"},"note":{"type":"string","description":"Optional notes related to the status.","maxLength":255,"nullable":true},"user":{"type":"string","description":"User ID who changed the status.","maxLength":50},"createdAt":{"type":"string","format":"date-time","description":"Date-time of status 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$"},"updatedAt":{"type":"string","format":"date-time","description":"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$"},"deletedAt":{"type":"string","format":"date-time","description":"Date-time of delete, if applicable.","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$","nullable":true}}}},"createdAt":{"type":"string","format":"date-time","description":"Date-time when the pickup request was created."},"updatedAt":{"type":"string","format":"date-time","description":"Date-time when the pickup request was last updated."},"deletedAt":{"type":"string","format":"date-time","description":"Date-time when the pickup request was deleted, if applicable.","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Retrieve list of courier pickup requests"}}}} ``` ## Create a courier pickup request > 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.\ > \ > This method is available to business clients in EU countries where Nova Post operates.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups":{"post":{"tags":["Pickups"],"description":"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. \n\n**Initial Status (`Draft`)**: The pickup request is created in the `Draft` status, which allows clients to add all necessary shipments to the request. \n\n**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.\n\n**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.\n\nThis method is available to business clients in EU countries where Nova Post operates.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Optional notes or instructions for the courier.","maxLength":255},"services":{"type":"array","items":{"type":"string"},"description":"List of additional services that can be included in the pickup request. This functionality is currently under development.","nullable":true},"phone":{"type":"string","description":"The contact phone number of the sender, required to allow the courier to reach out if necessary.","minLength":8,"maxLength":14},"email":{"type":"string","description":"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.","nullable":true},"fullName":{"type":"string","description":"Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.","maxLength":100},"companyTin":{"type":"string","description":"The tax identification number (TIN) of a legal entity.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Name of the company requesting the pickup.","minLength":2,"maxLength":255},"countryCode":{"type":"string","description":"ISO Alpha-2 code for the pickup location.","pattern":"^[A-Z]{2}$"},"addressParts":{"type":"object","description":"Detailed address information for the pickup location.","properties":{"city":{"type":"string","description":"The name of the city for the pickup location.","maxLength":100},"region":{"type":"string","description":"The administrative area, state, or region for the pickup.","maxLength":100},"street":{"type":"string","description":"The street name for the pickup location.","maxLength":100},"postCode":{"type":"string","description":"The postal code of the pickup location.","maxLength":10},"building":{"type":"string","description":"The building number or name at the pickup address.","maxLength":100},"flat":{"type":"string","description":"The apartment or office number within the building.","maxLength":10},"block":{"type":"string","description":"The specific block or section within a larger complex, if applicable.","maxLength":100},"note":{"type":"string","description":"Additional instructions for the courier to access the pickup location.","maxLength":100}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"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$","nullable":true}}}}}},"responses":{"201":{"description":"Pickup request created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the pickup request.","minimum":1},"number":{"type":"string","description":"Reference number for the pickup request.","pattern":"^[A-Z]{4}\\d{10}$"},"status":{"type":"string","description":"Current pickup status, representing the different stages in the pickup process.\nPossible values include:\n - Draft: Initial stage where the pickup request is created but not yet finalized.\n - Created: The pickup request has been created and is ready for processing.\n - AppointedCourier: A courier has been assigned to the pickup request.\n - InProgress: The pickup process is underway.\n - Done: The pickup has been successfully completed.\n - ClientCanceled: The pickup was canceled by the client.\n - NotCompleted: The pickup process could not be completed.\n - Deleted: The pickup request has been removed from the system.\n - ReceivedByCourier: The parcel has been received by the courier.\n"},"statusDateTime":{"type":"string","format":"date-time","description":"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$"},"source":{"type":"string","description":"Origin of the request, typically \"clientapi\".","maxLength":50},"executor":{"type":"string","description":"Assigned executor for the pickup, if any.","maxLength":50,"nullable":true},"companyTin":{"type":"string","description":"The tax identification number (TIN) of a legal entity.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Name of the company.","minLength":2,"maxLength":255},"fullName":{"type":"string","description":"Full name of the requester.","maxLength":100},"phone":{"type":"string","description":"Contact phone number.","minLength":8,"maxLength":14},"email":{"type":"string","description":"Contact email address, if applicable.","nullable":true},"countryCode":{"type":"string","description":"Country code for the pickup location.","pattern":"^[A-Z]{2}$"},"createdByUser":{"type":"string","description":"ID of the user who created the request.","maxLength":50},"deliveryPartner":{"type":"string","description":"Partner responsible for delivery, if any.","nullable":true},"lockVersion":{"type":"integer","description":"Version number for concurrency control.","minimum":1},"divisionId":{"type":"integer","description":"Division ID associated with the pickup, if applicable.","minimum":1,"nullable":true},"settlementId":{"type":"integer","description":"Settlement ID for the pickup location.","minimum":1},"cityDistrict":{"type":"string","description":"City district of the pickup location, if applicable.","maxLength":50,"nullable":true},"address":{"type":"object","description":"Formatted address and geolocation.","nullable":true,"properties":{"string":{"type":"string","description":"Complete address as a formatted string.","maxLength":255},"latitude":{"type":"number","format":"float","description":"Latitude of the pickup location.","minimum":-90,"maximum":90},"longitude":{"type":"number","format":"float","description":"Longitude of the pickup location.","minimum":-180,"maximum":180}}},"addressParts":{"type":"object","description":"Breakdown of address details, specified in request.","nullable":true,"properties":{"postCode":{"type":"string","description":"Postal code of the pickup location.","maxLength":10},"building":{"type":"string","description":"Building number of the pickup location.","maxLength":100},"street":{"type":"string","description":"Street name for the pickup location.","maxLength":100},"city":{"type":"string","description":"City name for the pickup location.","maxLength":100},"region":{"type":"string","description":"Region name for the pickup location.","maxLength":100},"flat":{"type":"string","description":"Flat or apartment number.","maxLength":10},"note":{"type":"string","description":"Additional notes for the address.","maxLength":100},"block":{"type":"string","description":"Block or building section.","maxLength":100,"nullable":true}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"Start of the pickup time window, specified in request.","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"End time for the pickup window, specified in request.","nullable":true},"note":{"type":"string","description":"Note or instructions for the courier.","maxLength":255,"nullable":true},"currencyCode":{"type":"string","description":"Currency code of the country used for payment transactions.","pattern":"^[A-Z]{3}$"},"externalId":{"type":"string","description":"Internal data, not for use.","nullable":true},"shipments":{"type":"array","items":{"type":"object"},"description":"List of shipments associated with this pickup request."},"services":{"type":"array","items":{"type":"object"},"description":"List of additional services that can be included in the pickup request. This functionality is currently under development."},"statuses":{"type":"array","description":"Array of status objects tracking pickup status changes.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique status identifier.","minimum":1},"pickupId":{"type":"integer","description":"Pickup request ID.","minimum":1},"status":{"type":"string","description":"Current pickup status, representing the different stages in the pickup process.\nPossible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.\n"},"dateTime":{"type":"string","format":"date-time","description":"Date and time of status 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$"},"note":{"type":"string","description":"Optional notes related to the status.","maxLength":255,"nullable":true},"user":{"type":"string","description":"User ID who changed the status.","maxLength":50},"createdAt":{"type":"string","format":"date-time","description":"Date-time of status 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$"},"updatedAt":{"type":"string","format":"date-time","description":"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$"},"deletedAt":{"type":"string","format":"date-time","description":"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$","nullable":true}}}},"createdAt":{"type":"string","format":"date-time","description":"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$"},"updatedAt":{"type":"string","format":"date-time","description":"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$"},"deletedAt":{"type":"string","format":"date-time","description":"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$","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Create a courier pickup request"}}}} ``` ## Update pickup request 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.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/status":{"put":{"description":"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`. \n\nWhile 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.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","tags":["Pickups"],"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the pickup request.","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"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.","enum":["Created"]},"lockVersion":{"type":"integer","description":"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.","minimum":1},"note":{"type":"string","description":"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.","maxLength":255}},"required":["id","status","lockVersion"]}}}},"responses":{"200":{"description":"Status updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the status update was successful."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Update pickup request status"}}}} ``` ## Update a courier pickup request > 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.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}":{"put":{"description":"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. \nThis method is available to business clients in EU countries where Nova Post operates.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","minimum":1},"description":"Unique identifier of the pickup request to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Optional notes or instructions for the courier.","maxLength":255},"services":{"type":"array","items":{"type":"string"},"description":"List of additional services that can be included in the pickup request. This functionality is currently under development.","nullable":true},"phone":{"type":"string","description":"The contact phone number of the sender, required to allow the courier to reach out if necessary.","minLength":8,"maxLength":14},"email":{"type":"string","description":"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.","nullable":true},"fullName":{"type":"string","description":"Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.","maxLength":100},"companyTin":{"type":"string","description":"The tax identification number (TIN) of a legal entity.","minLength":2,"maxLength":20},"companyName":{"type":"string","description":"Name of the company requesting the pickup.","minLength":2,"maxLength":255},"lockVersion":{"type":"integer","description":"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.","minimum":1},"countryCode":{"type":"string","description":"ISO Alpha-2 code for the pickup location.","pattern":"^[A-Z]{2}$"},"addressParts":{"type":"object","description":"Detailed address information for the pickup location.","properties":{"city":{"type":"string","description":"The name of the city for the pickup location.","maxLength":100},"region":{"type":"string","description":"The administrative area, state, or region for the pickup.","maxLength":100},"street":{"type":"string","description":"The street name for the pickup location.","maxLength":100},"postCode":{"type":"string","description":"The postal code of the pickup location.","maxLength":10},"building":{"type":"string","description":"The building number or name at the pickup address.","maxLength":100},"flat":{"type":"string","description":"The apartment or office number within the building.","maxLength":10},"block":{"type":"string","description":"The specific block or section within a larger complex, if applicable.","maxLength":100},"note":{"type":"string","description":"Additional instructions for the courier to access the pickup location.","maxLength":100}}},"pickedTimeFrom":{"type":"string","format":"date-time","description":"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$","nullable":true},"pickedTimeTo":{"type":"string","format":"date-time","description":"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$","nullable":true}}}}}},"responses":{"200":{"description":"Pickup request updated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the updated pickup request.","minimum":1},"number":{"type":"string","description":"Reference number for the pickup request.","pattern":"^[A-Z]{4}\\d{10}$"},"status":{"type":"string","description":"Current pickup status, representing the different stages in the pickup process.\nPossible values include:\n - Draft: Initial stage where the pickup request is created but not yet finalized.\n - Created: The pickup request has been created and is ready for processing.\n - AppointedCourier: A courier has been assigned to the pickup request.\n - InProgress: The pickup process is underway.\n - Done: The pickup has been successfully completed.\n - ClientCanceled: The pickup was canceled by the client.\n - NotCompleted: The pickup process could not be completed.\n - Deleted: The pickup request has been removed from the system.\n - ReceivedByCourier: The parcel has been received by the courier.\n"},"lockVersion":{"type":"integer","description":"Updated version number for concurrency control."},"note":{"type":"string","description":"Updated notes for the courier.","maxLength":255},"pickedTimeFrom":{"type":"string","format":"date-time","description":"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$"},"pickedTimeTo":{"type":"string","format":"date-time","description":"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$"},"addressParts":{"type":"object","description":"Updated address information for the pickup location.","properties":{"city":{"type":"string","description":"The name of the city for the pickup location.","maxLength":100},"region":{"type":"string","description":"The administrative area, state, or region for the pickup.","maxLength":100},"street":{"type":"string","description":"The street name for the pickup location.","maxLength":100},"postCode":{"type":"string","description":"The postal code of the pickup location.","maxLength":10},"building":{"type":"string","description":"The building number or name at the pickup address.","maxLength":100},"flat":{"type":"string","description":"The apartment or office number within the building.","maxLength":10},"block":{"type":"string","description":"The specific block or section within a larger complex, if applicable.","maxLength":100},"note":{"type":"string","description":"Additional instructions for the courier to access the pickup location.","maxLength":100}}},"statuses":{"type":"array","description":"Array of updated status objects tracking pickup status changes.","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Update a courier pickup request"}}}} ``` ## Delete a courier pickup request > 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.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}":{"delete":{"description":"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.\nThis method is available to business clients in EU countries where Nova Post operates.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","minimum":1},"description":"Unique identifier of the pickup request to be deleted."}],"responses":{"200":{"description":"Pickup request deleted successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"deletedAt":{"type":"string","format":"date-time","description":"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$"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Delete a courier pickup request"}}}} ``` ## Remove shipments from a pickup request > This endpoint allows removing specific shipments from an existing courier pickup request.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/shipments":{"delete":{"description":"This endpoint allows removing specific shipments from an existing courier pickup request.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","tags":["Pickups"],"parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the pickup request.","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","description":"A list of shipments to be removed from the pickup request.","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"The unique identifier of the shipment to be removed.","minimum":1}}}}}}}}},"responses":{"200":{"description":"Shipments removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","description":"Details of removed shipments.","items":{"type":"object","properties":{"deletedAt":{"type":"string","format":"date-time","description":"Date-time when the shipment was removed."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Remove shipments from a pickup request"}}}} ``` ## Add shipments to a courier pickup request > 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.\ > \ > šŸ”¹\*\*Description of control elements:\*\*\ > \ > \*\*SCHEMA\*\*\
\ > Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\ > \- \*\*Single line description\*\*\
\ > A description that fits into a single line; any text that does not fit remains hidden.\ > \- \*\*Multiline description\*\*\
\ > An expanded description that displays more than one line of text.\ > \ > \*\*EXAMPLE\*\*\
\ > Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
```json {"openapi":"3.0.0","info":{"version":"1.0.0"},"tags":[],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.pl/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Time-out":{"description":"Connection time-out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/pickups/{id}/shipments":{"post":{"description":"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.\nThis method is available to business clients in EU countries where Nova Post operates.\n\nšŸ”¹**Description of control elements:**\n\n**SCHEMA**
\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**
\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","tags":["Pickups"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","minimum":1},"description":"Unique identifier of the pickup request to which shipments are being added."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object","properties":{"shipmentId":{"type":"integer","description":"Unique identifier of the shipment to be added.","minimum":1}},"required":["shipmentId"]},"description":"List of shipments to be added to the pickup request."}}}}}},"responses":{"200":{"description":"Shipments successfully added to the pickup request.","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the pickup shipment record.","minimum":1},"pickupId":{"type":"integer","description":"Unique identifier of the associated pickup request.","minimum":1},"shipmentId":{"type":"integer","description":"Unique identifier of the added shipment.","minimum":1},"status":{"type":"string","description":"Indicates the current status of the shipment as part of the pickup request. This value is returned by the system and reflects the state of the shipment. Possible values: `Accepted`, `NotReady`, `NotPacked`, `ClientCanceled`, `Deleted`, `Added`.\n"},"note":{"type":"string","description":"Additional notes related to the shipment, if applicable.","nullable":true},"deliveryPartners":{"type":"array","description":"List of delivery partners associated with the shipment, if applicable.","items":{"type":"object"}},"createdAt":{"type":"string","format":"date-time","description":"Date-time when the shipment was added.","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$"},"updatedAt":{"type":"string","format":"date-time","description":"Date-time when the shipment 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$"},"deletedAt":{"type":"string","format":"date-time","description":"Date-time when the shipment record was deleted, if applicable.","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Add shipments to a courier pickup request"}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-portal.novapost.com/metodi-1/methods/pickups.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.