Dictionaries

Dictionaries are the source of the IDs you need when creating an order: regions, districts, branches (pickup points) and shipment statuses.

1. General

All requests are sent to {BASE_URL}/api/v2/dictionaries/... and require a Bearer token.

Authorization: Bearer {TOKEN}
Accept: application/json
Accept-Language: ru

Language matters: dictionaries are returned in uz and ru only. Sending Accept-Language: en (or omitting the header when the server default is en) returns error -210. Always send Accept-Language explicitly.

Methods:

Method	Endpoint	Purpose
GET	`/api/v2/dictionaries/regions`	List of regions
GET	`/api/v2/dictionaries/districts`	Districts of a region
GET	`/api/v2/dictionaries/branches`	Branches (pickup points)
GET	`/api/v2/dictionaries/states`	List of shipment statuses

Typical sequence:

regions  →  districts (region_id)  →  branches (district_id)

2. Regions

Returns the list of regions of Uzbekistan. Takes no parameters.

GET {BASE_URL}/api/v2/dictionaries/regions

GET {BASE_URL}/api/v2/dictionaries/regions
Authorization: Bearer {TOKEN}
Accept-Language: ru

Response (200)

{
  "success": true,
  "data": [
    { "id": 1, "name": "город Ташкент" },
    { "id": 2, "name": "Самаркандская область" }
  ]
}

Field	Type	Description
`id`	integer	Region ID — used in the `districts` request
`name`	string\|null	Region name (in the requested language)

3. Districts

Returns the districts that have at least one branch (pickup point). If region_id is passed — only the districts of that region.

GET {BASE_URL}/api/v2/dictionaries/districts

Parameter	Type	Required	Description
`region_id`	integer	No	Filter by region (must exist). Without it — districts of all regions
`our`	integer\|boolean	No	Filter by branch ownership: `1`/`true` — districts with at least one Starex-owned branch, `0`/`false` — districts with at least one partner pickup point. Without it — all
`page`	integer	No	Page number (starting from `1`)
`limit`	integer	No	Records per page. Defaults to `20`

The response is paginated: items, totalCount, limit, page. The default page size is 20 records and can be changed via limit.

The list contains only districts that have at least one branch. Districts without branches are not returned at all.

GET {BASE_URL}/api/v2/dictionaries/districts?region_id=1&page=1
Authorization: Bearer {TOKEN}
Accept-Language: ru

Response (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": 12, "regionId": 1, "name": "Чиланзарский район", "our": true },
      { "id": 13, "regionId": 1, "name": "Юнусабадский район", "our": false }
    ],
    "totalCount": 16,
    "limit": 20,
    "page": 1
  }
}

Field	Type	Description
`items[].id`	integer	District ID — the `sender_district_id` / `receiver_district_id` of an order
`items[].regionId`	integer\|null	Parent region ID
`items[].name`	string\|null	District name (in the requested language)
`items[].our`	boolean	`true` — the district has at least one Starex-owned branch, `false` — partner pickup points only. Note: here it is `true/false`, while `our` in the branches response is `1/0` (integer)
`totalCount`	integer	Total districts matching the filter
`limit`	integer	Records per page
`page`	integer	Current page

The our field and the our filter are not the same thing. The field reflects the district's actual state and does not depend on the filter: with ?our=0, a district that has both a partner point and a Starex branch still appears in the list, with our: true. Field names are returned in camelCase — e.g. regionId.

4. Branches (pickup points)

The list of branches where a shipment can be picked up. This ID is used as receiver_branch_id when creating an order.

GET {BASE_URL}/api/v2/dictionaries/branches

Parameter	Type	Required	Description
`district_id`	integer	No	Filter by district. Without it — all branches
`our`	integer\|boolean	No	Filter by branch ownership: `1` or `true` — Starex-owned branches only, `0` or `false` — partner pickup points only. Without it — all
`page`	integer	No	Page number (starting from `1`)
`limit`	integer	No	Records per page. Defaults to `20`

The response is paginated. The default page size is 20 records and can be changed via limit. Request the next page via page.

our values: only 0, 1, true, false are accepted. Any other value returns a 422 error. If the parameter is omitted (or sent empty), no filter is applied — the list contains branches of both types.

GET {BASE_URL}/api/v2/dictionaries/branches?district_id=12&page=1
Authorization: Bearer {TOKEN}
Accept-Language: ru

Starex-owned branches only:

GET {BASE_URL}/api/v2/dictionaries/branches?district_id=12&our=1&page=1
Authorization: Bearer {TOKEN}
Accept-Language: ru

Response (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 7,
        "name": "STAREX CHILONZOR",
        "address": "Чиланзарский район, проспект Бунёдкор, 12",
        "lat": "41.2856",
        "lon": "69.2034",
        "our": 1,
        "phone": "+998 71 200-00-00",
        "worktime": "09:00-18:00"
      }
    ],
    "totalCount": 34,
    "limit": 20,
    "page": 1
  }
}

Field	Type	Description
`items[].id`	integer	Branch ID — for `receiver_branch_id`
`items[].name`	string	Branch name
`items[].address`	string\|null	Address (in the requested language)
`items[].lat`	string\|null	Latitude
`items[].lon`	string\|null	Longitude
`items[].our`	integer	`1` — Starex-owned branch, `0` — partner pickup point
`items[].phone`	string\|null	Branch phone number. Returned as-is from the source system — no guaranteed format, may be empty
`items[].worktime`	string\|null	Working hours as free-form text (e.g. `09:00-18:00`). Do not parse it — show it to the user as-is
`totalCount`	integer	Total number of records
`limit`	integer	Records per page (the request's `limit`, `20` by default)
`page`	integer	Current page

Number of pages: ceil(totalCount / limit).

5. Statuses

The full list of shipment statuses. These codes arrive in the shipment statuses response and inside the webhook payload.

GET {BASE_URL}/api/v2/dictionaries/states

GET {BASE_URL}/api/v2/dictionaries/states
Authorization: Bearer {TOKEN}
Accept: application/json

Response (200) — part of the list

{
  "success": true,
  "data": [
    { "code": 0, "name": "Ожидает синхронизации", "advanced": "AWAITING_SYNC" },
    { "code": 1, "name": "Новый",                  "advanced": "NEW" },
    { "code": 9, "name": "Доставлен",              "advanced": "COMPLETE" }
  ]
}

Field	Type	Description
`code`	integer	Status code
`name`	string\|null	Status name — always in Russian
`advanced`	string\|null	Stable, language-neutral mnemonic code (`NEW`, `COMPLETE`, etc.)

Important: the list is not fixed — new statuses may appear. Do not rely on known codes only; handle an unknown code gracefully (for example, show it as “other status”).

6. Recommendations and errors

Dictionaries are updated regularly on the Starex side — do not fetch them on every call, cache them (for example, refresh once a day).
Store district and branch IDs on your side: those exact IDs are needed when creating an order.
Cache the status list separately and be ready for unknown codes.

Code	HTTP	Reason
`422`	422	`region_id` does not exist; `district_id` does not exist; on `/branches` an `our` value other than `0/1/true/false` (on `/districts` an unknown value is treated as `false`)
`401`	401	Token missing or invalid
`-423`	423	Account is locked
`-210`	200	Language not supported (send `uz` or `ru`)
`100`	200	Unexpected internal error

Example error response:

{
  "success": false,
  "error": {
    "code": -210,
    "message": "Selected language is not supported for this operation"
  }
}