Dictionaries

Find measurements

get

/dictionary/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.

Authorizations

AuthorizationstringRequired

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

Query parameters

limitinteger · int32Optional

Max number of records to return on page.

Default: 15Example: 1

pageinteger · int32Optional

Number of page to return

Example: 1

Responses

200

measurements

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/dictionary/measurements

GET /v.1.0/dictionary/measurements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 18,
  "per_page": 1,
  "total": 18,
  "from": null,
  "to": null,
  "items": [
    {
      "code": "cm",
      "name": "Centimeter",
      "shortName": "cm",
      "createdAt": "2022-09-29T09:16:04.000000Z",
      "updatedAt": "2023-06-29T12:48:09.000000Z",
      "deletedAt": null
    }
  ]
}

Find divisions

get

/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.

Authorizations

AuthorizationstringRequired

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

Query parameters

limitinteger · int32Optional

Max number of items to return.

Default: 15Example: 1

pageinteger · int32Optional

Page number to return.

Example: 1

settlementIds[]integer[]Optional

List of settlement identifiers used to filter divisions or terminals by their location. Each ID corresponds to a unique settlement in the system.

prohibitedSendingboolean · enumOptional

Indicates whether sending parcels from this division is available. If true – sending from this division is not possible.

Possible values:

prohibitedIssuanceboolean · enumOptional

Indicates whether parcel delivery to this division is available. If true – receiving parcels at this division is not possible.

Possible values:

latitudenumber · floatOptional

Geographical latitude of the division, used for positioning on maps and calculating distances. Example value: 49.8005164984.

longitudenumber · floatOptional

Geographical longitude of the division, used for positioning on maps and calculating distances. Example value: 22.9404162762.

Header parameters

Accept-languagestring · enumOptional

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

Possible values:

Responses

200

Divisions

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/divisions

GET /v.1.0/divisions HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 24942,
  "per_page": 1,
  "total": 24942,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 1,
      "name": "WROCŁAW 1",
      "shortName": "WROCŁAW 1",
      "externalId": "cf909742-1bee-4c97-8d0e-16de519c3220",
      "source": "NPAX",
      "countryCode": "PL",
      "settlement": {
        "id": 26061,
        "name": "Wroclaw",
        "region": {
          "id": 344,
          "name": "Wrocław County",
          "parent": {
            "id": 2,
            "name": "Lower Silesian voivodeship"
          }
        }
      },
      "address": "50-231, Polska, Województwo dolnośląskie, Wrocław County, Wrocław, Trzebnicka, 50/1A",
      "number": "50/1",
      "status": "Working",
      "customerServiceAvailable": true,
      "divisionCategory": "PostBranch",
      "publicPhones": [],
      "internalPhones": [],
      "responsiblePerson": "Dzhemesiuk Yaroslav",
      "partner": null,
      "ownerDivision": null,
      "latitude": 51.1271131131,
      "longitude": 17.0360840848,
      "distance": null,
      "maxWeightPlaceSender": 200000,
      "maxLengthPlaceSender": 3000,
      "maxWidthPlaceSender": 1700,
      "maxHeightPlaceSender": 1700,
      "maxWeightPlaceRecipient": 200000,
      "maxLengthPlaceRecipient": 3000,
      "maxWidthPlaceRecipient": 1700,
      "maxHeightPlaceRecipient": 1700,
      "prohibitedSending": false,
      "prohibitedIssuance": false,
      "maxCostPlace": 999999,
      "maxDeclaredCostPlace": 999999,
      "workSchedule": [
        {
          "day": "sunday",
          "from": "09:00",
          "to": "18:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "monday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "tuesday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "wednesday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "thursday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "friday",
          "from": "08:00",
          "to": "20:00",
          "breakFrom": null,
          "breakTo": null
        },
        {
          "day": "saturday",
          "from": "09:00",
          "to": "18:00",
          "breakFrom": null,
          "breakTo": null
        }
      ],
      "settings": [],
      "logisticsCode": "Code.1",
      "attributes": {
        "printFormDeliveryRegion": "Balty"
      },
      "createdAt": "2022-09-29T12:40:39.000000Z",
      "updatedAt": "2023-10-16T10:06:35.042931Z",
      "deletedAt": null,
      "fullAddress": {
        "country": "Poland",
        "settlement": "Wrocław",
        "street": "Trzebnicka",
        "building": "50/1A",
        "note": "",
        "zipcode": "50-231"
      }
    }
  ]
}

Find currencies

get

/dictionary/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.

Authorizations

AuthorizationstringRequired

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

Query parameters

limitinteger · int32Optional

Max number of items to return on page.

Default: 15Example: 1

pageinteger · int32Optional

Number of page to return.

Example: 1

codes[]string · int32Optional

Currencies codes.

Example: UAH

Responses

200

currencies

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/dictionary/currencies

GET /v.1.0/dictionary/currencies HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 1,
  "total": 1,
  "from": null,
  "to": null,
  "items": [
    {
      "code": "USD",
      "numCode": "840",
      "name": "US Dollar",
      "shortName": "US Dollar",
      "symbol": "$",
      "createdAt": "2022-09-27T11:55:52.000000Z",
      "updatedAt": "2022-09-27T11:55:52.000000Z",
      "deletedAt": null
    }
  ]
}

Find cargo classifiers (UKT ZED)

get

/dictionary/classifier

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.

Authorizations

AuthorizationstringRequired

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

Query parameters

country-codestringOptional

The ISO 3166-1 Alpha-2 code of the country for which the UKT ZED classifier is needed.

This parameter refers to the recipient country, not the sender.

The format of UKT ZED codes varies by country, example:

UA – Returns 8-digit codes.
CA or MD – Returns 10-digit codes.

Example: If you need UKT ZED codes for Canada, use country-code=CA.

Example: CA

fuzzyboolean · enumOptional

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.

Example: truePossible values:

keywordstringOptional

Search keyword for the classifier.

Example: book

localestringOptional

Language code according to ISO 639-1 standard.

Example: uk

sizeinteger · int32Optional

Number of matching classifiers to return.

Example: 15

Responses

200

List of cargo classifiers (UKT ZED)

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/dictionary/classifier

GET /v.1.0/dictionary/classifier HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "status": true,
  "source": "tda",
  "error": "",
  "items": [
    {
      "id": "b1f6e933-a5fd-3c76-8663-49ad7b454bdd",
      "hsCode": "85171400",
      "category": {
        "en": "Electronics",
        "currentLocal": "Електроніка"
      },
      "subCategory": {
        "en": "Laptops, Computers And Peripherals",
        "currentLocal": "Ноутбуки, комп'ютери та периферійні пристрої"
      },
      "keywords": {
        "en": "Avonic Video Conference Camera, System for video conferences, IP conference phone, Logitech ConferenceCam, Prestigio Solutions, UHD video conference camera, USB speakerphone, Device for conference communication, Wireless speakerphone, Video conference camera, VKZ camera, Video conference kit, Conference Lenovo hub, Speakerphone, Speaker system, Audio conference system, Conference phone, Video conference system, Notification system, System console",
        "currentLocal": "Avonic Video Conference Camera, Cистема для відеоконференцій, IP конференц телефон, Logitech ConferenceCam, Prestigio Solutions, UHD відео конференц камера, USB спікерфон, Апарат для конференц зв'язку, Бездротовий спікерфон, Камера відеоконференції, Камера ВКЗ, Комплект для відеоконференцзв'язку, Конференц хаб Lenovo, Спікерфон, Акустична система, Аудіо конференц система, Конференц-телефон, Система відеоконференції, Система оповіщення, Системна консоль"
      },
      "product": {
        "en": "Conference equipment",
        "currentLocal": "Конференц-обладнання"
      },
      "description": {
        "en": "Electrical machinery and equipment and parts thereof; sound recorders and reproducers, television image and sound recorders and reproducers, and parts and accessories of such articles | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, including apparatus for communication in a wired or wireless network (such as a local or wide area network), other than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528; parts thereof: | Telephone sets, including smartphones and other telephones for cellular networks or for other wireless networks : | Other telephones for cellular networks or for other wireless networks | Other",
        "currentLocal": "Електричні машини та обладнання та їх частини; апарати для запису та відтворення звуку, апарати для запису та відтворення телевізійного зображення та звуку, а також частини та приладдя до таких виробів | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж; інша апаратура для передачі або прийому голосу, зображень або інших даних, включаючи апаратуру для зв'язку в дротовій або бездротовій мережі (такій як локальна або глобальна мережа), крім апаратури для передачі або прийому товарних позицій 8443, 8525, 8527 або 8528; їх частини: | Телефонні апарати, включаючи смартфони та інші телефони для стільникових мереж або інших бездротових мереж: | Інші телефони для стільникових мереж або для інших бездротових мереж | Інший"
      },
      "exportFromUA": true,
      "importToUA": true
    }
  ]
}

Find customs-fees settings

get

/dictionary/customs-fees/{code}

This method returns recipient country settings used to determine whether customs duties can be paid by the sender, as well as the minimum and maximum declared parcel value thresholds within which this option is available.

If the customsFeesActive value is false, the sender cannot act as the customs-duty payer for the selected country.

The minDeclaredCost and maxDeclaredCost fields define the declared parcel value range (in the recipient country's currency) within which the option for customs-duty payment by the sender is available.

If the declared parcel value is lower than minDeclaredCost, customs duties are not applied to the parcel.

If the declared parcel value exceeds maxDeclaredCost, the sender cannot act as the customs-duty payer. In this case, the payerFeesCustoms parameter must be set to Recipient.

🔹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.

Authorizations

AuthorizationstringRequired

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

Path parameters

codestringRequired

Alpha-code of the destination country according to the ISO 3166-1 Alpha-2

Example: PL

Responses

200

Successful response with customs-fee configuration

application/json

401

Unauthorized

application/json

422

Unprocessable entity – invalid country code

application/json

503

Connection time-out

application/json

get

/dictionary/customs-fees/{code}

GET /v.1.0/dictionary/customs-fees/{code} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "customsFeesActive": true,
  "maxDeclaredCost": 500,
  "minDeclaredCost": 10
}

Settlement Prohibited Issuance Dictionary

get

/dictionary/settlements/prohibited-issuance

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.

Authorizations

AuthorizationstringRequired

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

Responses

200

Settlement prohibited issuance dictionary manifest

application/json

401

Unauthorized

application/json

404

Action not available

application/json

get

/dictionary/settlements/prohibited-issuance

GET /v.1.0/dictionary/settlements/prohibited-issuance HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "unix_time": 1766120417,
  "urls": [
    "https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/en/settlements.json.gz",
    "https://api-cdn.novapost.com/dictionary/settlements/prohibited-issuance/uk/settlements.json.gz"
  ]
}

Settlements Offline Dictionary

get

/dictionary/settlements/versions

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.

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.

Authorizations

AuthorizationstringRequired

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

Query parameters

countryCodestring · enumRequired

Country code for which the settlements dictionary should be returned (ISO 3166-1 Alpha-2).

Example: UAPossible values:

Header parameters

Accept-languagestring · enumOptional

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

Possible values:

Responses

200

Settlements offline dictionary manifest

application/json

401

Unauthorized

application/json

404

Action not available

application/json

503

Connection time-out

application/json

get

/dictionary/settlements/versions

GET /v.1.0/dictionary/settlements/versions?countryCode=UA HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "unix_time": 1776225628,
  "base_version": {
    "unix_time": 1776225628
  },
  "urls": [
    "https://api-cdn.novapost.com/dictionary/settlements/api/UA/uk/base.json.gz"
  ]
}

Find settlements

get

/dictionary/settlements

This API method enables you to get a list of settlements available in different countries. By providing the country code as a parameter, you can retrieve a complete list of settlements and their associated information. The method supports searching by street name. The response usually contains information such as the settlement name, identifier, country data, and other relevant attributes. This data can be useful for creating a transport document (shipment).

Authorizations

AuthorizationstringRequired

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

Query parameters

limitinteger · int32Optional

Max number of items to return.

Default: 15Example: 1

pageinteger · int32Optional

Page number to return.

Example: 1

textSearchstringOptional

Search by any text.

Responses

200

settlements

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/dictionary/settlements

GET /v.1.0/dictionary/settlements HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 80,
  "per_page": 15,
  "total": 1186,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 118064,
      "name": "місто Київ",
      "country": {
        "code": "UA",
        "name": "Україна"
      },
      "region": {
        "id": 406,
        "name": "Київська область",
        "parent": null
      },
      "latitude": 50.450418,
      "longitude": 30.523541,
      "postCode1": "01001",
      "postCode2": "04215",
      "alternativeNames": [
        "kyiv",
        "місто київ",
        "misto kiyiv",
        "город киев",
        "gorod kiev",
        "city kyiv"
      ],
      "externalId": "e718a680-4b33-11e4-ab6d-005056801329",
      "boost": 504,
      "prohibitedIssuance": false,
      "prohibitedSending": false,
      "createdAt": "2022-10-01T15:50:20.000000Z",
      "updatedAt": "2026-04-03T07:17:49.715827Z",
      "deletedAt": null
    }
  ]
}

Find streets

get

/dictionary/streets

This API method enables you to get a list of streets available in different settlements. By providing the country code as a parameter or settlementId as parameter, you can retrieve a complete list of streets and their associated information. The method also supports searching by street name. The response usually contains information such as the street name, settlement name, identifier and other relevant attributes. This data can be useful for creating a transport document (shipment).

Authorizations

AuthorizationstringRequired

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

Query parameters

countryCodes[]string[]Optional

List of country codes (ISO 3166-1 Alpha-2) to filter streets.

namestringOptional

Street name filter.

limitinteger · int32 · min: 1 · max: 100Optional

Max number of items to return.

Default: 15Example: 15

pageinteger · min: 1Optional

Page number to return.

Example: 1

Responses

200

streets

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/dictionary/streets

GET /v.1.0/dictionary/streets HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 50,
  "total": 16,
  "from": null,
  "to": null,
  "items": [
    {
      "id": 4582148,
      "name": "вул. Хрещатик",
      "settlement": {
        "id": 118064,
        "name": "місто Київ"
      },
      "countryCode": "UA",
      "latitude": 0,
      "longitude": 0,
      "alternativeNames": [
        "вул. хрещатик",
        "vul. khreshchatik",
        "крещатик",
        "kreshchatik",
        "khreshchatyk"
      ],
      "externalId": "ad090b1f-6845-11e6-8304-00505688561d",
      "createdAt": "2024-02-03T11:40:00.000000Z",
      "updatedAt": "2025-04-04T00:47:48.223218Z",
      "deletedAt": null
    }
  ]
}

PreviousAuthorization NextServices

Last updated 2 days ago