Find post offices · Metfone Express Documentation

GET /tms-partner/api/v1/department/posts

Usage and important notes

All query parameters are optional. query searches name, address, or phone; codeLocation filters by a province, district, or village. departmentCode targets one branch. Use total for pagination rather than the current items.length.

Provide both latDest and longDest to get a meaningful distance in kilometers and nearest-first sorting. Without them, do not assume distance has a useful value.

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
query	query	No	Search branch name/address/phone.
codeLocation	query	No	Province/district/village code, e.g. BAN.
departmentCode	query	No	Specific branch code, e.g. KOH01.
latDest	query	No	Destination latitude; send with longDest to obtain distance and nearest-first ordering.
longDest	query	No	Destination longitude used with latDest.
limit	query	No	Page size, default 20.
offset	query	No	Pagination offset, default 0.

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}/department/posts?query=Koh&departmentCode=KOH01&codeLocation=KOH&limit=20&offset=0&latDest=11.2&longDest=103.4" \
  --header "X-Api-Token: ${API_TOKEN}" \
  --header "X-Client-Source: ${PARTNER_CODE}" \
  --header "Accept-Language: en" \
  --header "Accept: application/json"

Example response

{
  "items": [
    {
      "department_id": 900001,
      "type": "POST",
      "code": "EXAMPLE-POST",
      "phone": "${POST_OFFICE_PHONE}",
      "name": "Example post office",
      "department_code": "EXAMPLE-POST",
      "country_code": "KH",
      "province_code": "BAN",
      "district_code": "0102",
      "ward_code": "010201",
      "home": "Example branch",
      "address": "Example branch, Cambodia",
      "latitude": 11.2,
      "longitude": 103.4,
      "distance": 3.2,
      "address_component": {
        "components": [
          {
            "name": "Example recipient, Street B",
            "type": "OTHER",
            "level": 999
          },
          {
            "id": "5025109",
            "code": "010201",
            "name": "បន្ទាយនាង",
            "type": "VILLAGE",
            "level": 3
          },
          {
            "id": "4059452",
            "code": "0102",
            "name": "មង្គលបូរី",
            "type": "DISTRICT",
            "level": 2
          },
          {
            "id": "4025109",
            "code": "BAN",
            "name": "Banteay Meanchey",
            "type": "PROVINCE",
            "level": 1
          },
          {
            "type": "NATIONAL",
            "name": "Cambodia",
            "code": "KH",
            "level": 0
          }
        ]
      }
    }
  ],
  "total": 1
}

Response fields

Field	Type	Required	Description
`items`	array	See description	Current page.
`items[].department_id`	number	See description	Internal branch ID.
`items[].type`	string	See description	Example: POST.
`items[].code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].phone`	string	See description	Branch phone.
`items[].name`	string	See description	Branch name.
`items[].department_code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].country_code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].province_code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].district_code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].ward_code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].home`	string	See description	Local address text.
`items[].address`	string	See description	Full branch address.
`items[].latitude`	number	See description	Branch latitude.
`items[].longitude`	number	See description	Branch longitude.
`items[].distance`	number	See description	Distance in km, meaningful only when latDest/longDest are supplied.
`items[].address_component`	object	See description	Branch address components.
`items[].address_component.components`	array	See description	Use current administrative API IDs and codes.
`items[].address_component.components[].id`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].address_component.components[].code`	string	See description	Use the identifier returned by the API, not the illustrative value.
`items[].address_component.components[].name`	string	See description	Location name or street address.
`items[].address_component.components[].type`	string	See description	NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level.
`items[].address_component.components[].level`	number	See description	0 country; 1 province; 2 district; 3 village; 999 street/detail.
`total`	number	See description	Total matches for pagination.

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.