List districts and villages

GET /tms-partner/api/v1/administrativedivision/country/{country-code}/{level}/{location-code}

Usage and important notes

For districts, request /administrativedivision/country/KH/2/BAN. For villages, use the district code: /administrativedivision/country/KH/3/0102. A district example uses Accept-Language: km. Store returned IDs/codes for address components in pricing and order creation. All response fields are the same as the province endpoint.

Authentication headers

Header	Requirement	Value / meaning
X-Api-Token	Required	`${API_TOKEN}`: environment-specific token issued by TMS
X-Client-Source	Required	`${PARTNER_CODE}`: partner code paired with the token
Content-Type	With a JSON body	application/json
Accept	Required by source	application/json
Accept-Language	Optional	`vn`, `en`, `my`, `km`, `lo`

Path and query parameters

Name	Location	Required	Description
country-code	path	Yes	ISO country code: KH Cambodia, LA Laos.
level	path	Yes	Requested child level: 2 districts or 3 villages.
location-code	path	Yes	Parent code: province BAN for level 2, district 0102 for level 3.
filter	query	No	Partial name match (LIKE) at every level of this endpoint.

cURL example

BASE_URL must include /tms-partner/api/v1. Load the token and partner code from your private environment; never paste secrets into documentation or AI prompts.

curl --request GET "${BASE_URL}/administrativedivision/country/KH/2/BAN" \
  --header "X-Api-Token: ${API_TOKEN}" \
  --header "X-Client-Source: ${PARTNER_CODE}" \
  --header "Accept-Language: en" \
  --header "Accept: application/json"

Example response

[
  {
    "id": 4059452,
    "level": 2,
    "status": 1,
    "code": "0102",
    "countrycode": "KH",
    "name": "មង្គលបូរី",
    "type": "DISTRICT",
    "short_name": "មង្គលបូរី",
    "parent_code": "BAN",
    "refs": [
      {
        "sys": "VTP",
        "code": "0102"
      }
    ]
  }
]

Response fields

Field	Type	Required	Description
`[].id`	number	See description	Internal location ID.
`[].level`	number	See description	Administrative level: 1 province, 2 district, 3 village.
`[].status`	number	See description	1 means active.
`[].code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`[].countrycode`	string	See description	Country code.
`[].name`	string	See description	Localized location name.
`[].type`	string	See description	PROVINCE, DISTRICT or VILLAGE.
`[].short_name`	string	See description	Short name.
`[].parent_code`	string	See description	Parent location code; generally country code at level 1.
`[].refs`	array	See description	References to other systems.
`[].refs[].sys`	string	See description	Reference system, e.g. VTP or POSTCODE.
`[].refs[].code`	string	See description	Use the identifier returned by the API, not the illustrative value.

Level-3 example

GET /tms-partner/api/v1/administrativedivision/country/KH/3/0102

[
  {
    "id": 5025109,
    "level": 3,
    "status": 1,
    "code": "010201",
    "countrycode": "KH",
    "name": "បន្ទាយនាង",
    "type": "VILLAGE",
    "short_name": "បន្ទាយនាង",
    "parent_code": "0102",
    "refs": [
      {
        "sys": "VTP",
        "code": "010201"
      }
    ]
  }
]

Error handling

See HTTP codes and source limitations. HTTP success does not prove COD, fees, or cancellation are correct; inspect the documented business fields. Do not assume create-order retries are safe.