# Find post offices

Search branches, paginate results, and optionally sort by distance.

Company: Metfone Express
API version: v1
Requested language: en
Content language: en
Source: https://mfexpress-partner-docs.zhst.app/mfexpress/en/post-offices

Endpoint: GET /department/posts


```http
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.
```bash
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

```json
{
  "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](reference). HTTP success does not prove COD, fees, or cancellation are correct; inspect the documented business fields. Do not assume create-order retries are safe.