---
title: "List states and provinces for a country by Country ID"
method: GET
path: "/api/v1/meta/provinces/{countryId}"
tags: ["Account Information", "Public API"]
---

# List states and provinces for a country by Country ID

`GET /api/v1/meta/provinces/{countryId}`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/meta/provinces/{countryId}`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `field`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/meta/provinces/:countryId/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the list of states or provinces for the specified country, sorted alphabetically by abbreviation (`options[].label`). Each item follows StateProvinceSchema: `label` is the subdivision abbreviation (e.g. "UT"), not the full name; `name` is the full subdivision name; `iso` is the ISO 3166-2 code (e.g. "US-UT"). Use a `countryId` from `GET /api/v1/meta/countries/options` (the `id` field on the row for the country) so it matches the countries list.

OAuth Scopes: field

## Path parameters

- `countryId` integer, required

## Response `200`

List of states/provinces. The `options` array items match StateProvinceSchema; `label` is always the subdivision abbreviation used for sorting.

- StateProvinceResponseSchema: Response from `GET /api/v1/meta/provinces/{countryId}`. The `options` list is sorted by `label` (subdivision abbreviation).
  - `options` StateProvinceSchema[]: Subdivisions for the requested `countryId`. Each object matches StateProvinceSchema; `label` is the subdivision abbreviation, `name` the full name, `iso` the ISO 3166-2 code.
    - `id` integer: State/province ID
    - `label` string: Subdivision abbreviation (e.g. "UT" for Utah). This is the short code used in `options[].label`, not the full name (see `name`).
    - `iso` string: ISO 3166-2 subdivision code (e.g. "US-UT" for Utah).
    - `name` string: Full subdivision name (e.g. "Utah"), distinct from the abbreviation in `label`.

## Other responses

- `400`: The provided country ID is invalid.

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)