Registers
The method allows the user to get information about their registries or registries related to their profile in the registry.
🔸Registries are automatically filtered by creation source (clientapi or bc) depending on the method used.
🔸Shipments that were removed from the registry are not included in the response.
Authorization JWT-token with a lifetime of 1 hour in header
Indicates that European registries should be returned.
trueUnique registry identifiers for which information should be retrieved. This parameter is required if the numbers parameter is not specified.
85544Unique registry number for which information should be retrieved. This parameter is required if the ids parameter is not specified.
CRPL0000004829Unique settlement identifier.
22326When set to true, the response includes extended shipment information in the shipmentsInfo array.
If omitted or set to false, the response contains only shipmentId and shipmentNumber in the shipments array.
trueStart date of the registry filtering period. Used to retrieve records created from this date onwards (inclusive). The createdAtFrom field must be a date before createdAtTo
23.09.2025End date of the registry filtering period. Used to retrieve records created before this date (exclusive).
25.09.2025Number of page to return.
1Max number of items to return on page.
10Registries list
Indicates the current page number in the paginated response.
Total number of available pages calculated.
Number of registry records returned per page.
Total number of registries that match the request criteria.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
GET /v.1.0/registry HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1,
"items": [
{
"id": "948086",
"number": "CRPL0000041723",
"createdAt": "2026-05-19T14:46:28.232000Z",
"updatedAt": "2026-05-20T07:01:01.787000Z",
"deletedAt": null,
"posted": false,
"printed": false,
"description": "new name",
"status": "Open",
"type": "Client",
"createdByUser": "255ea89d-8c1f-47ec-8f2e-64486bd24f5f",
"scannedBarcodesAmount": 0,
"source": "clientapi",
"companyId": null,
"companyTin": "",
"companyName": "Private person",
"fullName": "Oksana Hrechaniuk",
"phone": "48512345678",
"countryCode": "PL",
"country": "Poland",
"settlementId": "22326",
"settlementName": "Warsaw",
"divisionId": "1888318",
"divisionName": "Post branch 11",
"address": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ",
"addressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Stanisława Wojciechowskiego",
"streetId": null,
"postCode": "02-495",
"building": "39 lok.1",
"flat": "",
"block": "",
"latitude": 52.1947201268,
"longitude": 20.8706685393,
"note": null
},
"currencyCode": "PLN",
"shipmentsInfo": [
{
"id": "3168550",
"number": "SHPL0462195188",
"totalWeight": 2000,
"totalCost": 65,
"currencyCode": "PLN",
"invoice": true
}
]
}
]
}The method is used to create a client registry of shipments, which combines multiple shipments into a single document for further processing.
This method is available for shipments from anywhere in the world to anywhere in the world.
Limitations for working with registers:
A shipment can be added to a register only if the sender’s data (city, counterparty, address) are identical for all shipments being added.
A shipment can be added only to one register — the same document cannot be added to multiple registers simultaneously.
A shipment can be added to a register only until an express waybill has been created for it (or until the shipment has been scanned at a Nova Post branch/unit).
A shipment marked for deletion cannot be added to a register.
The maximum number of shipments in a single register is 100.
Authorization JWT-token with a lifetime of 1 hour in header
Registry creation request
Name of the registry.
Array of unique shipment numbers for World parcels. Each shipment must belong to the same sender.
Registry successfully created.
Unique identifier of the registry.
Registry number in the format:
CR + alpha country code from the first shipment + unique number.
Registry version tracking identifier.
Registry status. After creation, the status is Open.
Registry creation date.
Registry update date.
Registry deletion date.
Registry posting status.
Registry printing status.
Number of shipments in the registry.
Number of shipments pending scanning.
Registry name specified during creation.
Sender company identifier.
Sender company TIN.
Sender phone number.
Sender country code in ISO 3166-1 alpha-2 format.
Sender settlement identifier.
Sender settlement name.
Sender division identifier.
Sender division name.
Full sender address string.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
POST /v.1.0/registry HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 64
{
"description": "My_new_registry",
"shipments": [
"SHPL0462195188"
]
}{
"id": 948086,
"number": "CRPL0000041723",
"versionTracking": null,
"status": "Open",
"createdAt": "2026-05-19T14:46:28.232180Z",
"updatedAt": "2026-05-19T14:46:28.232180Z",
"deletedAt": null,
"posted": null,
"printed": null,
"scannedBarcodesAmount": 1,
"forScanBarcodesAmount": 0,
"description": "My_new_registry",
"senderCompanyId": null,
"senderCompanyTin": "",
"senderPhone": "48512345678",
"senderCountryCode": "PL",
"senderSettlementId": "22326",
"senderSettlementExternalId": null,
"senderSettlementName": "Warsaw",
"senderDivisionId": "1888318",
"senderDivisionExternalId": null,
"senderDivisionName": "Post branch 11",
"senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ",
"senderAddressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Stanisława Wojciechowskiego",
"streetId": null,
"postCode": "02-495",
"building": "39 lok.1",
"flat": "",
"block": "",
"latitude": 52.1947201268,
"longitude": 20.8706685393,
"note": "",
"addressId": null
},
"shipments": [
{
"shipmentId": "1401932",
"shipmentNumber": "SHPL0462195188",
"destinationDivision": {
"name": "WARSZAWA 11",
"id": 1888318,
"number": "02/11"
}
}
]
}This method allows users to add a parcel to an existing shipment registry, which simplifies further shipping.
The method supports:
European shipments (shipment numbers such as
SHPL...)Ukrainian shipments (MEN/ID identifiers)
Limitations for working with registers:
This method is available for shipments from anywhere in the world to anywhere in the world.
A shipment can be added to a register only if the sender’s data (city, counterparty, address) are identical for all shipments being added.
A shipment can be added to only one register — the same document cannot be added to multiple registers simultaneously.
A shipment can be added to a register only until an express waybill has been created for it (or until the shipment has been scanned at a Nova Poshta branch/unit).
A shipment marked for deletion cannot be added to a register.
The maximum number of shipments in a single register is 100.
This method is used to add already created shipments to an existing registry.
Authorization JWT-token with a lifetime of 1 hour in header
Unique register identifier to which the shipment will be added.
111111Array of shipment identifiers that should be added to the registry. Each shipment must belong to the same sender.
Registry
Unique identifier of the registry.
Registry number.
Registry version number.
Registry status.
Date of registry creation.
Date of registry update.
Date of registry deletion.
Mark of registry post.
Mark of registry print.
Number of shipments in the registry.
User name of the registry.
Sender company identifier.
Sender company TIN.
Sender phone number.
Sender country code.
Sender settlement identifier.
External settlement identifier.
Sender settlement name.
Sender division identifier.
External division identifier.
Sender division name.
Full sender address.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
POST /v.1.0/registry/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"shipments": [
"SHPL8187197311"
]
}{
"id": "948086",
"number": "CRPL0000041723",
"versionTracking": null,
"status": "Open",
"createdAt": "2026-05-19T14:46:28.232000Z",
"updatedAt": "2026-05-19T14:46:28.574000Z",
"deletedAt": null,
"posted": false,
"printed": false,
"scannedBarcodesAmount": 2,
"description": "My_new_registry",
"senderCompanyId": null,
"senderCompanyTin": "",
"senderPhone": "48512345678",
"senderCountryCode": "PL",
"senderSettlementId": "22326",
"senderSettlementExternalId": null,
"senderSettlementName": "Warsaw",
"senderDivisionId": "1888318",
"senderDivisionExternalId": null,
"senderDivisionName": "Post branch 11",
"senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ",
"senderAddressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Stanisława Wojciechowskiego",
"streetId": null,
"postCode": "02-495",
"building": "39 lok.1",
"flat": "",
"block": "",
"latitude": 52.1947201268,
"longitude": 20.8706685393,
"note": null,
"addressId": null
},
"shipments": [
{
"shipmentId": "3168550",
"shipmentNumber": "SHPL0462195188"
},
{
"shipmentId": "3168827",
"shipmentNumber": "SHPL8187197311"
}
]
}The method allows users to delete shipment from an existing client registry.
The method supports:
European shipments (shipment numbers such as
SHPL...)Ukrainian shipments (MEN/ID identifiers)
Authorization JWT-token with a lifetime of 1 hour in header
Unique register identifier from which the shipment must be removed.
111111Array of shipment identifiers that should be removed from the registry. Each shipment must belong to the same sender.
Shipment successfully removed from registry.
Unique registry identifier.
Registry number.
Registry version number.
Registry status.
Registry creation date and time.
Registry update date and time.
Registry deletion date and time.
Indicates whether the registry has been posted.
Indicates whether the registry has been printed.
Number of shipments in the registry.
Registry name.
Sender company identifier.
Sender company TIN.
Sender phone number.
Sender country code (ISO Alpha-2).
Sender settlement identifier.
External settlement identifier.
Sender settlement name.
Sender division identifier.
External division identifier.
Sender division name.
Sender address.
Structured sender address.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
DELETE /v.1.0/registry/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"shipments": [
"SHPL8187197311"
]
}{
"id": "948086",
"number": "CRPL0000041723",
"versionTracking": null,
"status": "Open",
"createdAt": "2026-05-19T14:46:28.232000Z",
"updatedAt": "2026-05-19T14:46:28.574000Z",
"deletedAt": null,
"posted": false,
"printed": false,
"scannedBarcodesAmount": 1,
"description": "My_new_registry",
"senderCompanyId": null,
"senderCompanyTin": "",
"senderPhone": "48512345678",
"senderCountryCode": "PL",
"senderSettlementId": "22326",
"senderSettlementExternalId": null,
"senderSettlementName": "Warsaw",
"senderDivisionId": "1888318",
"senderDivisionExternalId": null,
"senderDivisionName": "Post branch 11",
"senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ",
"senderAddressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Stanisława Wojciechowskiego",
"streetId": null,
"postCode": "02-495",
"building": "39 lok.1",
"flat": "",
"block": "",
"latitude": 52.1947201268,
"longitude": 20.8706685393,
"note": null,
"addressId": null
},
"shipments": [
{
"shipmentId": "3168550",
"shipmentNumber": "SHPL0462195188"
}
]
}The method allows users to rename an existing registry.
The method supports:
European shipments (shipment numbers such as
SHPL...)Ukrainian shipments (MEN/ID identifiers)
Authorization JWT-token with a lifetime of 1 hour in header
Unique register identifier.
111111New name of registry.
Request successful. The registry was renamed.
Unique registry identifier.
Registry number.
Registry version number.
Registry status.
Registry creation date and time.
Registry update date and time.
Registry deletion date and time.
Indicates whether the registry has been posted.
Indicates whether the registry has been printed.
Number of shipments in the registry.
Registry name.
Sender company identifier.
Sender company TIN.
Sender phone number.
Sender country code (ISO Alpha-2).
Sender settlement identifier.
External settlement identifier.
Sender settlement name.
Sender division identifier.
External division identifier.
Sender division name.
Sender address.
Structured sender address.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
PUT /v.1.0/registry/{id}/rename HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"description": "new name"
}{
"id": "948086",
"number": "CRPL0000041723",
"versionTracking": null,
"status": "Open",
"createdAt": "2026-05-19T14:46:28.232000Z",
"updatedAt": "2026-05-19T14:46:28.574000Z",
"deletedAt": null,
"posted": false,
"printed": false,
"scannedBarcodesAmount": 1,
"description": "new name",
"senderCompanyId": null,
"senderCompanyTin": "",
"senderPhone": "48512345678",
"senderCountryCode": "PL",
"senderSettlementId": "22326",
"senderSettlementExternalId": null,
"senderSettlementName": "Warsaw",
"senderDivisionId": "1888318",
"senderDivisionExternalId": null,
"senderDivisionName": "Post branch 11",
"senderAddress": "02-495, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Stanisława Wojciechowskiego, 39 lok.1, , , ",
"senderAddressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Stanisława Wojciechowskiego",
"streetId": null,
"postCode": "02-495",
"building": "39 lok.1",
"flat": "",
"block": "",
"latitude": 52.1947201268,
"longitude": 20.8706685393,
"note": null,
"addressId": null
},
"shipments": [
{
"shipmentId": "3168550",
"shipmentNumber": "SHPL0462195188"
}
]
}The method allows users to delete an existing registry.
🔸Currently, deleting the registry is only possible after deleting all shipments from the registry.
The method supports:
European shipments (shipment numbers such as
SHPL...)Ukrainian shipments (MEN/ID identifiers)
Authorization JWT-token with a lifetime of 1 hour in header
Unique register identifier of the registry to be deleted.
111111Request successful. The registry was deleted.
Indicates whether the registry was successfully deleted.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
DELETE /v.1.0/registry/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"success": true
}The method allows users to receive a generated PDF file with a list of client parcels for further printing.
The response is returned as a generated file and contains a printable register with the list of shipments included in the selected registry.
Authorization JWT-token with a lifetime of 1 hour in header
Registry identifier in the system.
85544Type of printable document.
Applicable only to Ukrainian registries.
Available values:
international- international shipment documentsinvoice- shipment invoicesmarking- shipment marking labels
internationalPossible values: Marking print size.
Applicable only to Ukrainian registries.
Required for type=marking.
size_100_100Possible values: Number of copies of the printed document.
1Example: 2Generated file.
Unprocessable entity.
Internal Server Error.
GET /v.1.0/registry/print?id=1 HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
binaryLast updated