Get states

Overview

Get the states/regions for the given country_code as {label, value} pairs, ordered by name. The endpoint caches the result forever under states_list_v2_{country_code}.

Prerequisites

• No authentication required — this endpoint is public.
• The required country_code query parameter — a country code from the Get countries lookup. See Request below.

Base URL

Endpoint

GET /api/v1/address/states

Authentication

• No authentication required. This is a public reference endpoint — partner and account tokens may call it, but none is needed.

• The list is global and identical for every caller; there is no role scoping.

• The web app typically calls it before login.

Rate limit

• 100 requests/min.

Query parameters

• Query: country_code (string, required) — must be a known country code.

Response

• data.data[] (array of objects) — states for that country.
• value (string) — state code.
• label (string) — state name.

200 Success · 200

{
  "data": {
    "data": [
      { "value": "CA", "label": "California" },
      { "value": "NY", "label": "New York" },
      { "value": "TX", "label": "Texas" }
    ]
  }
}

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/address/states?country_code=US" \
  --header 'Accept: application/json'