List States

Description

Returns all states of the country associated with the authenticated user. In addition to state information (ID, name, and abbreviation), the response also includes the complete hierarchy of cities belonging to each state and, within each city, the list of neighborhoods. This endpoint can be useful for registrations, filters, and any functionality that requires structured geographic data.

NOTE. Available for use with branch access key and also with General ADM access key.

🔑 Query Parameters

No parameters are required. The list of states is returned automatically based on the country of the authenticated user.

📤 Response Structure

The response returns the list of states, containing the complete hierarchy of cities and associated neighborhoods.

Field	Type	Description
idState	int32	Identifier of the state.
name	string	Name of the state.
abbreviation	string	Abbreviation of the state (e.g., SP, RJ).
idCountry	int32	Identifier of the country to which the state belongs.
cities	array/	List of cities belonging to the state. See the structure below.

🧩 Structure of the cities object

Field	Type	Description
idCity	int32	Identifier of the city.
idState	int32	Identifier of the state to which the city belongs.
name	string	Name of the city.
neighborhoods	array/	List of neighborhoods belonging to the city. See the structure below.

🧩 Structure of the neighborhoods object

Field	Type	Description
idNeighborhood	int32	Identifier of the neighborhood.
idCity	int32	Identifier of the city to which the neighborhood belongs.
description	string	Name or description of the neighborhood.