Countries
Flow Summary
The current country-data flow is:
Step 1. Load the country listGET /api/v2/countries
Step 2. Load nationalities if the form needs themGET /api/v2/nationalities
Step 3. Load states for a selected countryGET /api/v2/countries/{id}/states
Step 4. Load cities for a selected stateGET /api/v2/states/{id}/cities
This route is not listed in the current public-route whitelist, so treat it as a protected route unless your middleware setup explicitly exposes it.
Authorization: Bearer <access_token>
Language Behavior
- The handler reads
Accept-Language - If the header is empty, it defaults to English
- Only exact
zhswitches the returnednamefield to Chinese - Any other value still returns the English name
1. List Countries
GET /api/v2/countries
Returns the current country list from the countries table.
Response fields
Each country item includes:
idnamecodedial_codelogo
Important backend behavior
- The repository only returns rows where
deleted_at IS NULL - When
Accept-Language: zh, the backend usesname_zhif present - If
name_zhis empty, it falls back to the normalname
Success response shape
{
"status_code": 200,
"message": "Success",
"data": [
{
"id": 114,
"name": "Singapore",
"code": "SG",
"dial_code": "65",
"logo": "https://..."
}
]
}
Integration Notes
- Use this for country pickers in registration, KYC, and card-request forms.
- Do not hardcode the country list in the app if you want logo and localized-name support to stay in sync with the backend.
2. List Nationalities
GET /api/v2/nationalities
Returns the nationality list used by the v2 KYC and cardholder flows.
Notes
- This route follows the same
Accept-Languagebehavior as the countries endpoint - Use it when the UI needs nationality-specific pickers instead of the country list
3. List States By Country
GET /api/v2/countries/{id}/states
Returns all states for one selected country.
Path parameter
idis the numeric country ID
Notes
- This is a v2-only geo helper route
- Use it for cascading address forms after the user has selected a country
4. List Cities By State
GET /api/v2/states/{id}/cities
Returns all cities for one selected state.
Path parameter
idis the numeric state ID
Notes
- This is the final level of the current v2 geo picker flow
- Use it after loading states from
GET /api/v2/countries/{id}/states