# Dictionaries ## Find measurements > This API method allows you to retrieve a list of measurement units like pieces or meters or kilos, that you can use to specify your items by metric system. The response will include details of each measurement unit, such as the unit code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).\
\ > \ > ๐Ÿ”น\*\*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":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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":{"/dictionary/measurements":{"get":{"tags":["Dictionaries"],"description":"This API method allows you to retrieve a list of measurement units like pieces or meters or kilos, that you can use to specify your items by metric system. The response will include details of each measurement unit, such as the unit code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
\n\n๐Ÿ”น**Description of control elements:**\n\n**SCHEMA**
\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n\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**
\n\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":"limit","description":"Max number of records 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":"measurements","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page.","minimum":1},"last_page":{"type":"integer","description":"Total pages found.","minimum":1},"per_page":{"type":"integer","description":"Current objects` limit for a single page.","minimum":1},"total":{"type":"integer","description":"Total objects found.","minimum":0},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true},"items":{"type":"array","description":"List of measurement`s units that you can use to specify your items by metric system.","items":{"type":"object","properties":{"code":{"type":"string","description":"Code of measurement`s unit."},"name":{"type":"string","description":"Name of measurement`s unit.","minLength":2,"maxLength":100},"shortname":{"type":"string","description":"Abbreviation of measurement`s unit.","minLength":1,"maxLength":20},"createdAt":{"type":"string","description":"Datetime when the item was added to the list."},"updatedAt":{"type":"string","description":"Datetime of the item`s update."},"deletedAt":{"type":"string","description":"Datetime if removed, otherwise is null.","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Find measurements"}}}} ``` ## Find divisions > This API method enables you to obtain a list of own and partner\`s cargo warehouses (divisions) and parcel lockers available within countries. By providing the country code as a parameter, you can retrieve a comprehensive list of cargo warehouses and related details. The response will typically include information like warehouse name, number, address, ID, country and city details, warehouse type, and other relevant attributes. This data can be useful to generate a transportation document (shipment).\ > \ > ๐Ÿ”น\*\*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":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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":{"/divisions":{"get":{"tags":["Dictionaries"],"description":"This API method enables you to obtain a list of own and partner`s cargo warehouses (divisions) and parcel lockers available within countries. By providing the country code as a parameter, you can retrieve a comprehensive list of cargo warehouses and related details. The response will typically include information like warehouse name, number, address, ID, country and city details, warehouse type, and other relevant attributes. This data can be useful to generate a transportation document (shipment).\n\n๐Ÿ”น**Description of control elements:**\n\n**SCHEMA**\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n\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**
\n\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","parameters":[{"in":"header","name":"Accept-language","description":"To receive warehouse description in a certain language please put required language code (ISO 639-1 standard) in a header parameter with a name - accept-language. If there is no translation for the selected language, then English will be displayed","schema":{"type":"string","enum":["cz","de","en","es","fr","et","hu","it","lt","lv","nl","pl","ro","sk","uk"]}},{"in":"query","name":"countryCodes[]","description":"To receive a list of cargo warehouses and parcel lockers in a certain country please choose required country code from the list. Use code, according to the ISO 3166-1 Alpha-2 standard.","schema":{"type":"array","items":{"type":"string","enum":["CZ","DE","EE","ES","FR","GB","HU","IT","LT","LV","MD","NL","PL","RO","SK","UA"]}}},{"in":"query","name":"limit","description":"Max number of items to return.","schema":{"type":"integer","format":"int32","default":15}},{"in":"query","name":"page","description":"Page number to return.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"settlementIds[]","description":"List of settlement identifiers used to filter divisions or terminals by their location. Each ID corresponds to a unique settlement in the system.","schema":{"type":"array","items":{"type":"integer"}}},{"in":"query","name":"divisionCategories[]","description":"Defines the operational category of a division to specify its type and function within the logistics network. Use one or multiple categories from the list.","schema":{"type":"array","items":{"type":"string","enum":["Postomat","PostBranch","CargoBranch","PUDO"]}}},{"in":"query","name":"statuses[]","description":"Filters divisions by their operational status. Indicates whether the branch is active, temporarily closed, or in preparation for opening.","schema":{"type":"array","items":{"type":"string","enum":["Working","NotWorking","NotWorkingTemporary","InProcessOpening"]}}},{"in":"query","name":"prohibitedSending","description":"Indicates whether sending parcels from this division is available. If `true` โ€“ sending from this division is not possible.","schema":{"type":"boolean","enum":[true,false]}},{"in":"query","name":"prohibitedIssuance","description":"Indicates whether parcel delivery to this division is available. If `true` โ€“ receiving parcels at this division is not possible.","schema":{"type":"boolean","enum":[true,false]}},{"in":"query","name":"latitude","description":"Geographical latitude of the division, used for positioning on maps and calculating distances. Example value: 49.8005164984.","schema":{"type":"number","format":"float"}},{"in":"query","name":"longitude","description":"Geographical longitude of the division, used for positioning on maps and calculating distances. Example value: 22.9404162762.","schema":{"type":"number","format":"float"}}],"responses":{"200":{"description":"Divisions","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page.","minimum":1},"last_page":{"type":"integer","description":"Total pages found.","minimum":1},"per_page":{"type":"integer","description":"Current objects` limit for a single page.","minimum":1},"total":{"type":"integer","description":"Total objects found.","minimum":0},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Warehouse`s id code.","minimum":1},"name":{"type":"string","description":"Description of warehouse.","minLength":1},"shortName":{"type":"string","description":"Short description of warehouse.","minLength":1},"externalId":{"type":"string","description":"Internal data, not for use."},"source":{"type":"string","description":"Source of information about a division (for instance, NPUA, NPAX, InPost, NPDepartment, NPMD1C, GLS_CZ, DPD, Venipak, SPS, ExpressOne. The list grows as additional partners are incorporated).","nullable":true},"countryCode":{"type":"string","description":"Country code where warehouse is located according to the ISO 3166-1 Alpha-2 standard.","pattern":"^[A-Z]{2}$"},"settlement":{"type":"object","description":"Detailed information about the location where the warehouse is located.","properties":{"id":{"type":"integer","description":"City`s id code.","minimum":1},"name":{"type":"string","description":"City or town name.","minLength":2},"region":{"type":"object","description":"District of city`s location.","properties":{"id":{"type":"integer","description":"District`s id code.","minimum":1},"name":{"type":"string","description":"District name.","minLength":2},"parent":{"type":"object","description":"Region of city`s location.","properties":{"id":{"type":"integer","description":"Region`s id code.","minimum":1},"name":{"type":"string","description":"Region name.","minLength":2}},"required":["id","name"]}},"required":["id","name","parent"]}},"required":["id","name","region"]},"address":{"type":"string","description":"Warehouse`s address.","maxLength":255},"number":{"type":"string","description":"Warehouse number.","maxLength":255},"status":{"type":"string","description":"Indicates the current operational state of the division. Possible values states are Working, NotWorking, NotWorkingTemporary, InProcessOpening."},"customerServiceAvailable":{"type":"boolean","description":"Availability of customer service in the division. Internal data, not for use."},"divisionCategory":{"type":"string","description":"Warehouse type."},"publicPhones":{"type":"array","items":{"type":"string"},"description":"Public phone of the division. Internal data, not for use."},"internalPhones":{"type":"array","items":{},"description":"Internal phone of the division. Internal data, not for use."},"responsiblePerson":{"type":"integer","description":"Responsible person for the division. Internal data, not for use.","nullable":true},"partner":{"type":"integer","description":"Internal data, not for use.","nullable":true},"ownerDivision":{"type":"integer","description":"Internal data, not for use.","nullable":true},"latitude":{"type":"number","description":"Latitude coordinate.","nullable":true},"longitude":{"type":"number","description":"Longitude coordinate.","nullable":true},"distance":{"type":"integer","nullable":true},"maxWeightPlaceSender":{"type":"integer","description":"Maximum weight of a single parcel that can be dispatched from this division, measured in grams."},"maxLengthPlaceSender":{"type":"integer","description":"Maximum length of a single parcel that can be dispatched from this division, measured in millimeters."},"maxWidthPlaceSender":{"type":"integer","description":"Maximum width of a single parcel that can be dispatched from this division, measured in millimeters."},"maxHeightPlaceSender":{"type":"integer","description":"Maximum height of a single parcel that can be dispatched from this division, measured in millimeters."},"maxWeightPlaceRecipient":{"type":"integer","description":"Maximum weight of a single parcel that can be received to this division, measured in grams."},"maxLengthPlaceRecipient":{"type":"integer","description":"Maximum length of a single parcel that can be received to this division, measured in millimeters."},"maxWidthPlaceRecipient":{"type":"integer","description":"Maximum width of a single parcel that can be received to this division, measured in millimeters."},"maxHeightPlaceRecipient":{"type":"integer","description":"Maximum height of a single parcel that can be received to this division, measured in millimeters."},"maxCostPlace":{"type":"number","description":"Max cost for one shipment.","minimum":0.01},"maxDeclaredCostPlace":{"type":"number","description":"Max declared cost for one shipment.","minimum":0.01},"workSchedule":{"type":"array","description":"Working schedule of warehouse. Returns an array with working days and times.","items":{"type":"object","properties":{"day":{"type":"string","description":"Working day of the week."},"from":{"type":"string","description":"Time when the warehouse begins its operations is returns in a 24-hour format."},"to":{"type":"string","description":"Time when the warehouse closes, returned in a 24-hour format."},"breakFrom":{"type":"string","description":"The start time of the break. Null if there is no break. Returned in 24-hour format.","nullable":true},"breakTo":{"type":"string","description":"The end time of the break. Null if there is no break. Returned in 24-hour format.","nullable":true}}}},"settings":{"type":"array","items":{}},"logisticsCode":{"type":"string","description":"A logistics district code used exclusively for the country of **Moldova** to determine the regional processing zone and routing direction of the shipment.
\n\n๐Ÿ”ธ**It is a key parameter required for correct allocation across logistics routes.**\n"},"attributes":{"type":"object","description":"Used to display additional parameters.","properties":{"printFormDeliveryRegion":{"type":"string","description":"A delivery branch code used exclusively for the country of **Moldova**. It represents a sub-category of the destination city and is applied to determine the primary logistics hub to which the shipment is initially directed before further distribution to the specific city or locality."}}},"createdAt":{"type":"string","description":"Datetime when the item was added to the list."},"updatedAt":{"type":"string","description":"Datetime of the item`s update."},"deletedAt":{"type":"string","description":"Datetime if removed, otherwise is null.","nullable":true},"fullAddress":{"type":"object","description":"Warehouse`s address split in parts.","properties":{"country":{"type":"string","description":"Country of warehouse.","maxLength":100},"settlement":{"type":"string","description":"City name of warehouse.","maxLength":100},"street":{"type":"string","description":"Street name of warehouse.","maxLength":100},"building":{"type":"string","description":"Building of warehouse.","maxLength":100},"note":{"type":"string","description":"Additional information about address.","maxLength":100},"zipcode":{"type":"string","description":"Post code.","maxLength":10}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Find divisions"}}}} ``` ## Find currencies > This API method allows you to retrieve a list of currencies that are available for creating transportation documents. By making a request with this method, you can obtain a list of currencies supported by the system. The response will include details of each currency, such as the currency code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).\
\ > \ > ๐Ÿ”น\*\*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":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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":{"/dictionary/currencies":{"get":{"tags":["Dictionaries"],"description":"This API method allows you to retrieve a list of currencies that are available for creating transportation documents. By making a request with this method, you can obtain a list of currencies supported by the system. The response will include details of each currency, such as the currency code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
\n\n๐Ÿ”น**Description of control elements:**\n\n**SCHEMA**
\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n\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**
\n\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":"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"}},{"in":"query","name":"codes[]","description":"Currencies codes.","schema":{"type":"string","format":"int32"}}],"responses":{"200":{"description":"currencies","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page.","minimum":1},"last_page":{"type":"integer","description":"Total pages found.","minimum":1},"per_page":{"type":"integer","description":"Current objects` limit for a single page.","minimum":1},"total":{"type":"integer","description":"Total objects found.","minimum":0},"from":{"type":"integer","nullable":true},"to":{"type":"integer","nullable":true},"items":{"type":"array","description":"List of currencies that are available for creating transportation documents.","items":{"type":"object","properties":{"code":{"type":"string","description":"Currency code according to the iso-4217 standard.","pattern":"^[A-Z]{3}$"},"numCode":{"type":"integer","description":"Numerical currency code according to the iso-4217 standard."},"name":{"type":"string","description":"Full currency name.","minLength":2,"maxLength":100},"shortName":{"type":"string","description":"Short currency name.","minLength":1,"maxLength":20},"symbol":{"type":"integer","description":"Sign, symbol, short designation of the name of a monetary unit."},"createdAt":{"type":"string","description":"Datetime when the item was added to the list."},"updatedAt":{"type":"string","description":"Datetime of the item`s update."},"deletedAt":{"type":"string","description":"Datetime if removed, otherwise is null.","nullable":true}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Find currencies"}}}} ``` ## Find cargo classifiers (UKT ZED) > This API method allows you to retrieve a list of cargo classifiers (UKT ZED). Cargo classifiers are predefined categories or classifications used to categorize different types of cargo. By making a request to this method, you can obtain a list of cargo classifiers supported by the system. The response will include details of each classifier, such as the classifier ID, name, description, category, examples and any other relevant information. This data can be useful to generate a transportation document (shipment).\ > \*\*How it works:\*\*\ > \- The method returns classifiers for the recipient country specified in\ > the \`country-code\` parameter.\ > \ > \- The format of UKT ZED codes depends on the selected country, example:\ > \- For destination countries \*\*Canada (CA)\*\* and \*\*Moldova (MD)\*\*, UKT ZED codes are strictly validated to be exactly \*\*10 digits\*\*.\ > \- Any non-numeric characters included in the \`HsCode\` will be automatically removed before validation.\ > \- The \`keyword\` parameter enables searching for a specific product classifier.\ > \ > \- If \`fuzzy=true\`, the search will include similar results based on approximate matching.\ > \ > \*\*Limitations:\*\*\ > \ > \- Some countries may not support UKT ZED retrieval via API.\ > \- Results depend on the latest classifier database updates.\
\ > \ > ๐Ÿ”น\*\*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":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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":{"/dictionary/classifier":{"get":{"tags":["Dictionaries"],"description":"This API method allows you to retrieve a list of cargo classifiers (UKT ZED). Cargo classifiers are predefined categories or classifications used to categorize different types of cargo. By making a request to this method, you can obtain a list of cargo classifiers supported by the system. The response will include details of each classifier, such as the classifier ID, name, description, category, examples and any other relevant information. This data can be useful to generate a transportation document (shipment).\n **How it works:**\n- The method returns classifiers for the recipient country specified in\nthe `country-code` parameter.\n\n- The format of UKT ZED codes depends on the selected country, example:\n - For destination countries **Canada (CA)** and **Moldova (MD)**, UKT ZED codes are strictly validated to be exactly **10 digits**.\n - Any non-numeric characters included in the `HsCode` will be automatically removed before validation.\n- The `keyword` parameter enables searching for a specific product classifier.\n\n- If `fuzzy=true`, the search will include similar results based on approximate matching.\n\n**Limitations:**\n\n- Some countries may not support UKT ZED retrieval via API.\n- Results depend on the latest classifier database updates.
\n\n๐Ÿ”น**Description of control elements:**\n\n\n**SCHEMA**
\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n\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**
\n\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":"country-code","description":"The ISO 3166-1 Alpha-2 code of the country for which the UKT ZED\nclassifier is needed.\n\nThis parameter refers to the **recipient country**, not the sender.\n\nThe format of UKT ZED codes varies by country, example:\n\n- `UA` โ€“ Returns 8-digit codes.\n- `CA` or `MD` โ€“ Returns 10-digit codes. \n\n**Example:** If you need UKT ZED codes for Canada, use\n`country-code=CA`.\n","schema":{"type":"string"}},{"in":"query","name":"fuzzy","description":"Search mechanism enables to include results that closely resemble the query terms or have some degree of similarity, expanding the search scope to include variations or similar entries.","schema":{"type":"boolean","enum":[true,false]}},{"in":"query","name":"keyword","description":"Search keyword for the classifier.","schema":{"type":"string"}},{"in":"query","name":"locale","description":"Language code according to ISO 639-1 standard.","schema":{"type":"string"}},{"in":"query","name":"size","description":"Number of matching classifiers to return.","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"List of cargo classifiers (UKT ZED)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean"},"source":{"type":"string"},"error":{"type":"string"},"items":{"type":"array","description":"List of classifiers that correspond to the requested keyword. Returns null if there is no match.","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"Classifier ID."},"hsCode":{"type":"string","description":"Code of ะกargo classifiers (UKT ZED) dictionary."},"category":{"type":"object","description":"Classifier`s category.","properties":{"en":{"type":"string","description":"Name of the category in English."},"currentLocal":{"type":"string","description":"Name of the category in the language according to the parameter - locale."}},"required":["en","currentLocal"]},"subCategory":{"type":"object","description":"Classifier`s subcategory.","properties":{"en":{"type":"string","description":"Name of the subcategory in English."},"currentLocal":{"type":"string","description":"Name of the subcategory in the language according to the parameter - locale."}},"required":["en","currentLocal"]},"keywords":{"type":"object","description":"Keywords for the subcategory.","properties":{"en":{"type":"string","description":"Keywords in English."},"currentLocal":{"type":"string","description":"Keywords in the language according to the parameter - locale."}},"required":["en","currentLocal"]},"product":{"type":"object","description":"Name of the product of the classifier.","properties":{"en":{"type":"string","description":"Name in English."},"currentLocal":{"type":"string","description":"Name in the language according to the parameter - locale."}},"required":["en","currentLocal"]},"description":{"type":"object","description":"Description of the products which corresponding the classifier.","properties":{"en":{"type":"string","description":"Description in English."},"currentLocal":{"type":"string","description":"Description in the language according to the parameter - locale."}},"required":["en","currentLocal"]},"exportFromUA":{"type":"boolean"},"importToUA":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Validation"},"503":{"$ref":"#/components/responses/Time-out"}},"summary":"Find cargo classifiers (UKT ZED)"}}}} ``` ## Find customs-fees settings > This method provides country-specific rules that determine whether a sender from Ukraine is allowed to pay customs duties and the maximum declared parcel value for which this option is permitted.\ > \ > \ > If the returned \`declaredCost\` limit is exceeded, the sender cannot act as the customs-fee payer.\ > \ > \ > In such cases, the \`payerFeesCustoms\` parameter must be set to \`Recipient\`, as only the recipient is allowed to pay the customs duties for parcels exceeding this value.\
\ > \ > \ > ๐Ÿ”น\*\*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":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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"}}}},"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":{"/dictionary/customs-fees/{code}":{"get":{"tags":["Dictionaries"],"summary":"Find customs-fees settings","description":"This method provides country-specific rules that determine whether a sender from Ukraine is allowed to pay customs duties and the maximum declared parcel value for which this option is permitted.\n\n\nIf the returned `declaredCost` limit is exceeded, the sender cannot act as the customs-fee payer.\n\n\nIn such cases, the `payerFeesCustoms` parameter must be set to `Recipient`, as only the recipient is allowed to pay the customs duties for parcels exceeding this value.
\n\n\n๐Ÿ”น**Description of control elements:**\n\n\n**SCHEMA**
\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n\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**
\n\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","parameters":[{"in":"path","name":"code","required":true,"description":"Alpha-code of the destination country.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response with customs-fee configuration","content":{"application/json":{"schema":{"type":"object","properties":{"customFeeActive":{"type":"boolean","description":"Indication of the possibility of paying customs duties by the sender.\nPossible values:\n - `true` โ€” payment is possible\n - `false` โ€” payment is not possible"},"declaredCost":{"type":"number","description":"Maximum parcel value (in the recipient country's currency) for which the sender may pay customs duties."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Unprocessable entity โ€“ invalid country code","content":{"application/json":{"schema":{"type":"object","properties":{"ErrorMessage":{"type":"string"}}}}}},"503":{"$ref":"#/components/responses/Time-out"}}}}}} ``` ## Settlement Prohibited Issuance Dictionary > This API method returns a manifest with links to offline dictionary files listing Ukrainian settlements where shipment issuance (pickup) is prohibited. The dictionary covers all settlement types and is intended for address validation, delivery availability checks, and logistics restrictions.\
\ > \ > The response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and prohibition flags.\
\ > \ > The dictionary files are distributed as localized compressed JSON archives.\
\ > \ > ๐Ÿ”น\*\*Key features:\*\*\ > \ > \- Returns a JSON manifest with URLs to dictionary files.\ > \- Files are provided in \`.json.gz\` format.\ > \- Localization supported (\`locale="uk"\`, \`locale="en"\`).\ > \- Includes only settlements with \`prohibitedIssuance = true\`.\ > \- Designed for offline usage and periodic synchronization.\
\ > \ > ๐Ÿ”น\*\*Description of control elements:\*\*\
\ > \ > \*\*SCHEMA\*\*\
\ > \ > Displays the full technical structure of the response objects, including field names, data types, nullability, and validation rules.\ > \ > \- \*\*Single line description\*\*\
\ > A compact description shown in short view.\ > \- \*\*Multiline description\*\*\
\ > An expanded description providing detailed explanations.\
\ > \ > \*\*EXAMPLE\*\*\
\ > \ > Shows a ready-made JSON response containing the dictionary manifest and an example of settlement records from the offline files.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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"}}}}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"object","properties":{"":{"type":"string"}}}}}}},"paths":{"/dictionary/settlements/prohibited-issuance":{"get":{"tags":["Dictionaries"],"summary":"Settlement Prohibited Issuance Dictionary","description":"This API method returns a manifest with links to offline dictionary files listing Ukrainian settlements where shipment issuance (pickup) is prohibited. The dictionary covers all settlement types and is intended for address validation, delivery availability checks, and logistics restrictions.
\n\nThe response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and prohibition flags.
\n\nThe dictionary files are distributed as localized compressed JSON archives.
\n\n๐Ÿ”น**Key features:**\n\n- Returns a JSON manifest with URLs to dictionary files.\n- Files are provided in `.json.gz` format.\n- Localization supported (`locale=\"uk\"`, `locale=\"en\"`).\n- Includes only settlements with `prohibitedIssuance = true`.\n- Designed for offline usage and periodic synchronization.
\n\n๐Ÿ”น**Description of control elements:**
\n\n**SCHEMA**
\n\nDisplays the full technical structure of the response objects, including field names, data types, nullability, and validation rules.\n\n- **Single line description**
\n A compact description shown in short view.\n- **Multiline description**
\n An expanded description providing detailed explanations.
\n\n**EXAMPLE**
\n\nShows a ready-made JSON response containing the dictionary manifest and an example of settlement records from the offline files.\n","parameters":[],"responses":{"200":{"description":"Settlement prohibited issuance dictionary manifest","content":{"application/json":{"schema":{"type":"object","required":["unix_time","urls"],"properties":{"unix_time":{"type":"integer","description":"Unix timestamp indicating the dictionary generation time."},"urls":{"type":"array","description":"List of URLs to localized offline dictionary files.","items":{"type":"string","format":"uri"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Action not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}} ``` ## Settlements Offline Dictionary > This API method returns a manifest with links to offline dictionary files containing settlements. The dictionaries are generated based on the settlements dataset and provided separately per country.\
\ > \ > The response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and other relevant attributes.\
\ > \ > Each request returns dictionary files for a specific country.\
\ > \ > The dictionary files are distributed as localized compressed JSON archives.\
\ > \ > ๐Ÿ”น\*\*Key features:\*\* \ > \- Returns a JSON manifest with URLs to dictionary files. \ > \- Files are provided in \`.json.gz\` format. \ > \- Localization supported via \`Accept-language\` header (default: \`en\`). \ > \- Separate files per country (\`UA\`, \`MD\`). \ > \- Based on settlements dictionary data. \ > \- Updated once per day. \ > \- Designed for offline usage and periodic synchronization.\
\ > \ > ๐Ÿ”น\*\*Description of control elements:\*\*\
\ > \ > \*\*SCHEMA\*\*\
\ > \ > Displays the full technical structure of the response objects, including field names, data types, nullability, and validation rules.\ > \ > \- \*\*Single line description\*\*\
\ > A compact description shown in short view.\ > \- \*\*Multiline description\*\*\
\ > An expanded description providing detailed explanations.\
\ > \ > \*\*EXAMPLE\*\*\
\ > \ > Shows a ready-made JSON response containing the dictionary manifest and an example of settlement records from the offline files.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Dictionaries"}],"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"}}}},"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":{"/dictionary/settlements/versions":{"get":{"tags":["Dictionaries"],"summary":"Settlements Offline Dictionary","description":"This API method returns a manifest with links to offline dictionary files containing settlements. The dictionaries are generated based on the settlements dataset and provided separately per country.
\n\nThe response contains URLs to the latest localized dictionary files prepared for offline usage. Each file includes settlement data such as administrative hierarchy, coordinates, postal codes, alternative names, and other relevant attributes.
\n\nEach request returns dictionary files for a specific country.
\n\nThe dictionary files are distributed as localized compressed JSON archives.
\n\n๐Ÿ”น**Key features:** \n- Returns a JSON manifest with URLs to dictionary files. \n- Files are provided in `.json.gz` format. \n- Localization supported via `Accept-language` header (default: `en`). \n- Separate files per country (`UA`, `MD`). \n- Based on settlements dictionary data. \n- Updated once per day. \n- Designed for offline usage and periodic synchronization.
\n\n๐Ÿ”น**Description of control elements:**
\n\n**SCHEMA**
\n\nDisplays the full technical structure of the response objects, including field names, data types, nullability, and validation rules.\n\n- **Single line description**
\n A compact description shown in short view.\n- **Multiline description**
\n An expanded description providing detailed explanations.
\n\n**EXAMPLE**
\n\nShows a ready-made JSON response containing the dictionary manifest and an example of settlement records from the offline files.\n","parameters":[{"in":"header","name":"Accept-language","description":"To receive dictionary content in a certain language please put required language code (ISO 639-1 standard) in a header parameter with a name - accept-language. If there is no translation for the selected language, then English will be displayed","schema":{"type":"string","enum":["en","ro","uk"]}},{"in":"query","name":"countryCode","description":"Country code for which the settlements dictionary should be returned (ISO 3166-1 Alpha-2).","required":true,"schema":{"type":"string","enum":["UA","MD"]}}],"responses":{"200":{"description":"Settlements offline dictionary manifest","content":{"application/json":{"schema":{"type":"object","required":["unix_time","base_version","urls","real_urls"],"properties":{"unix_time":{"type":"integer","description":"Unix timestamp indicating the dictionary generation time."},"base_version":{"type":"object","description":"Base version metadata of the dictionary.","required":["unix_time"],"properties":{"unix_time":{"type":"integer","description":"Unix timestamp of the base dictionary version."}}},"urls":{"type":"array","description":"List of public URLs to localized offline dictionary files.","items":{"type":"string","format":"uri"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Action not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"503":{"$ref":"#/components/responses/Time-out"}}}}}} ``` --- # 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/dictionaries.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.