Overview The States API (Departamentos) allows you to manage state or department records in the system. States are the middle level of the geographic hierarchy: Country → State → City.
In the Core Projects system, “Departamento” refers to a state, province, or administrative division within a country.
Model Structure Table: departamentosPrimary Key: id_departamentoFields Unique identifier for the state/department
State/department name (max 100 characters)
Foreign key reference to the parent country
Record creation timestamp
Record last update timestamp
Relationships The parent country object
Collection of cities belonging to this state/department
List All States curl --request GET \ --url https://api.coreprojects.com/api/departamentos \ --header 'Authorization: Bearer YOUR_TOKEN'
{ "success" : true , "data" : [ { "id_departamento" : 1 , "nombre" : "Cundinamarca" , "id_pais" : 1 , "created_at" : "2024-01-15T10:35:00.000000Z" , "updated_at" : "2024-01-15T10:35:00.000000Z" , "pais" : { "id_pais" : 1 , "nombre" : "Colombia" , "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" }, "ciudades" : [ { "id_ciudad" : 1 , "nombre" : "Bogotá" , "codigo_postal" : "110111" , "id_departamento" : 1 , "created_at" : "2024-01-15T10:40:00.000000Z" , "updated_at" : "2024-01-15T10:40:00.000000Z" } ] }, { "id_departamento" : 2 , "nombre" : "Antioquia" , "id_pais" : 1 , "created_at" : "2024-01-15T11:00:00.000000Z" , "updated_at" : "2024-01-15T11:00:00.000000Z" , "pais" : { "id_pais" : 1 , "nombre" : "Colombia" , "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" }, "ciudades" : [ { "id_ciudad" : 2 , "nombre" : "Medellín" , "codigo_postal" : "050001" , "id_departamento" : 2 , "created_at" : "2024-01-15T11:05:00.000000Z" , "updated_at" : "2024-01-15T11:05:00.000000Z" } ] } ] }
Endpoint Response Fields Indicates if the request was successful
Array of state/department objects with nested country and cities data
Get Single State curl --request GET \ --url https://api.coreprojects.com/api/departamentos/1 \ --header 'Authorization: Bearer YOUR_TOKEN'
200 - Success
404 - Not Found
{ "success" : true , "data" : { "id_departamento" : 1 , "nombre" : "Cundinamarca" , "id_pais" : 1 , "created_at" : "2024-01-15T10:35:00.000000Z" , "updated_at" : "2024-01-15T10:35:00.000000Z" , "pais" : { "id_pais" : 1 , "nombre" : "Colombia" , "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" }, "ciudades" : [ { "id_ciudad" : 1 , "nombre" : "Bogotá" , "codigo_postal" : "110111" , "id_departamento" : 1 , "created_at" : "2024-01-15T10:40:00.000000Z" , "updated_at" : "2024-01-15T10:40:00.000000Z" } ] } }
Endpoint GET /api/departamentos/{id}
Path Parameters The unique identifier of the state/department
Create State curl --request POST \ --url https://api.coreprojects.com/api/departamentos \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "nombre": "Cundinamarca", "id_pais": 1 }'
201 - Created
422 - Validation Error
422 - Invalid Country
{ "success" : true , "message" : "Departamento creado exitosamente" , "data" : { "id_departamento" : 1 , "nombre" : "Cundinamarca" , "id_pais" : 1 , "created_at" : "2024-01-15T10:35:00.000000Z" , "updated_at" : "2024-01-15T10:35:00.000000Z" , "pais" : { "id_pais" : 1 , "nombre" : "Colombia" , "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" } } }
Endpoint Body Parameters Name of the state/department (max 100 characters)
ID of the parent country (must exist in the countries table)
Validation Rules
nombre: Required, string, maximum 100 charactersid_pais: Required, must exist in the pais table
Update State curl --request PUT \ --url https://api.coreprojects.com/api/departamentos/1 \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "nombre": "Cundinamarca - DC", "id_pais": 1 }'
200 - Success
404 - Not Found
422 - Validation Error
{ "success" : true , "message" : "Departamento actualizado exitosamente" , "data" : { "id_departamento" : 1 , "nombre" : "Cundinamarca - DC" , "id_pais" : 1 , "created_at" : "2024-01-15T10:35:00.000000Z" , "updated_at" : "2024-01-15T14:20:00.000000Z" , "pais" : { "id_pais" : 1 , "nombre" : "Colombia" , "created_at" : "2024-01-15T10:30:00.000000Z" , "updated_at" : "2024-01-15T10:30:00.000000Z" } } }
Endpoint PUT /api/departamentos/{id}
Path Parameters The unique identifier of the state/department to update
Body Parameters Updated name of the state/department (max 100 characters)
Updated parent country ID (must exist in the countries table)
Delete State curl --request DELETE \ --url https://api.coreprojects.com/api/departamentos/1 \ --header 'Authorization: Bearer YOUR_TOKEN'
200 - Success
404 - Not Found
409 - Conflict
{ "success" : true , "message" : "Departamento eliminado exitosamente" }
Endpoint DELETE /api/departamentos/{id}
Path Parameters The unique identifier of the state/department to delete
Business Rules A state/department cannot be deleted if it has associated cities. You must first delete all cities before deleting the state.
Get States by Country curl --request GET \ --url https://api.coreprojects.com/api/paises/1/departamentos \ --header 'Authorization: Bearer YOUR_TOKEN'
{ "success" : true , "data" : [ { "id_departamento" : 1 , "nombre" : "Cundinamarca" , "id_pais" : 1 , "created_at" : "2024-01-15T10:35:00.000000Z" , "updated_at" : "2024-01-15T10:35:00.000000Z" , "ciudades" : [ { "id_ciudad" : 1 , "nombre" : "Bogotá" , "codigo_postal" : "110111" , "id_departamento" : 1 , "created_at" : "2024-01-15T10:40:00.000000Z" , "updated_at" : "2024-01-15T10:40:00.000000Z" } ] }, { "id_departamento" : 2 , "nombre" : "Antioquia" , "id_pais" : 1 , "created_at" : "2024-01-15T11:00:00.000000Z" , "updated_at" : "2024-01-15T11:00:00.000000Z" , "ciudades" : [ { "id_ciudad" : 2 , "nombre" : "Medellín" , "codigo_postal" : "050001" , "id_departamento" : 2 , "created_at" : "2024-01-15T11:05:00.000000Z" , "updated_at" : "2024-01-15T11:05:00.000000Z" } ] } ] }
Endpoint GET /api/paises/{id_pais}/departamentos
Path Parameters The unique identifier of the country
Description Retrieve all states/departments that belong to a specific country. Each state includes its associated cities.
Relationships Parent Relationship
Country (Pais) : Each state belongs to one country. See the Countries API for country management.
Child Relationship
Cities (Ciudades) : Each state can have multiple cities. Use the following endpoint to get cities for a specific state:
GET /api/departamentos/{id_departamento}/ciudades
See the Cities API documentation for more details. 