API Reference - States

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108121

← Back to API Reference | Getting Started

States

The States table is a global reference list of regions (states, provinces, territories) keyed by country. These records are used throughout the platform for member location fields, search filtering, and geographic data validation. This is a read-only reference table; while CRUD endpoints are available, typical usage is GET operations only to look up valid state/region codes and names.

Model name in URL: list_states — DB table: list_states

The State Object

FieldTypeDescription
region_idintegerUnique region ID (primary key, read-only)
country_idstringISO 3166-1 alpha-2 country code this region belongs to (EG US, CA); max 4 characters
codestringShort region code (EG NY, ON); max 15 characters, unique
namestringFull region name (EG New York, Ontario); max 255 characters

List States

GET /api/v2/list_states/get

Returns a paginated list of state/region records.

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/list_states/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "region_id": "1",
      "country_id": "US",
      "code": "AL",
      "name": "Alabama"
    },
    {
      "region_id": "2",
      "country_id": "US",
      "code": "AK",
      "name": "Alaska"
    }
  ],
  "total": "73",
  "current_page": 1,
  "total_pages": 3,
  "next_page": "MipfKjI="
}

Retrieve a State Record

GET /api/v2/list_states/get/{region_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/list_states/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "region_id": "1",
      "country_id": "US",
      "code": "AL",
      "name": "Alabama"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Create a State Record

POST /api/v2/list_states/create

Creates a new state/region record. This endpoint is available but not typically needed as the platform ships with a complete region list.

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/list_states/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "country_id=US" \
  -d "code=XX" \
  -d "name=Example Region"

Example Response

Copy
{
  "status": "success",
  "message": {
    "region_id": "74",
    "country_id": "US",
    "code": "XX",
    "name": "Example Region"
  }
}

Update a State Record

PUT /api/v2/list_states/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/list_states/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "region_id=74" \
  -d "name=Updated Region Name"

Example Response

Copy
{
  "status": "success",
  "message": {
    "region_id": "74",
    "country_id": "US",
    "code": "XX",
    "name": "Updated Region Name"
  }
}

Delete a State Record

DELETE /api/v2/list_states/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/list_states/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "region_id=74"

Example Response

Copy
{
  "status": "success",
  "message": "list_states record was deleted"
}