Get country divisions (states/provinces)

Overview

Returns the administrative subdivisions of a country - regions, provinces, states - in the shape expected by a select control. Needed at registration: when a country has subdivisions, state_select is required on POST /api/v1/auth/register and its value comes from here.

Controller: App\Http\Controllers\Api\V1\Public\CountryController::divisions()
Route name: api.v1.public.countries.divisions

Authentication

Type: None (public endpoint)
Additional middleware: throttle:public. See docs/api/README.md §14.

Request

Method: GET
Path: /api/v1/public/countries/{code}/divisions

Path parameters

Parameter	Type	Description
`{code}`	`string(2)`	ISO 3166-1 alpha-2 country code. Constrained by the route to two letters (`[A-Za-z]{2}`)

Example request

Response `200 OK`

data is an array, unlike GET /api/v1/public/countries which returns a keyed object. Captured live; truncated to the first 3 of 110 entries for Italy.

{
  "success": true,
  "status": "success",
  "message": "OK",
  "data": [
    { "label": "Agrigento", "value": "AG@Agrigento" },
    { "label": "Alessandria", "value": "AL@Alessandria" },
    { "label": "Ancona", "value": "AN@Ancona" }
  ]
}

Response fields

Field	Type	Nullable	Always present	Description
`data[].label`	`string`	No	Yes	Subdivision name, for display
`data[].value`	`string`	No	Yes	Composite: `{code}@{name}`, e.g. `AG@Agrigento`

value is the string to send back in state_select at registration. AuthController::register() splits it on @ into state_code and state. Do not build it yourself and do not send the code alone.

A country with no subdivisions returns an empty array, not a 404.

Errors

`422 Unprocessable Entity` — code not recognised

Domain rejection from the controller, so it carries the full envelope and has no errors key. Captured live:

{
  "success": false,
  "status": "error",
  "message": "Invalid country code"
}

`429 Too Many Requests`

Behind the dedicated public limiter (300 requests per minute, keyed by IP). No errors key.

{
  "success": false,
  "status": "error",
  "message": "Too many requests"
}

Notes

Read-only despite living under a resource-like path.

Subdivision names are in the country's own language: Italian provinces come back in Italian regardless of Accept-Language.

Unlike GET /api/v1/public/countries/{code}, an unrecognised code gives 422 here and 404 there. The two endpoints treat the same error differently - this is unchanged from the removed utility pair.

Replaces POST /api/v1/utility/country/divisions (removed; see docs/api/_archive/utility/POST_country_divisions.md).

Get country divisions (states/provinces)

Overview#

Authentication#

Request#

Path parameters#

Example request#

Response 200 OK#

Response fields#

Errors#

422 Unprocessable Entity — code not recognised#

429 Too Many Requests#

Notes#

Request

Responses

Overview

Authentication

Request

Path parameters

Example request

Response `200 OK`

Response fields

Errors

`422 Unprocessable Entity` — code not recognised

`429 Too Many Requests`

Notes