Skip to main content

​
Overview

The Institutions API allows you to manage educational institutions, including their contact information, academic year configuration, and institutional details.

​
Endpoints

MethodEndpointDescription
GET/api/institutionsList all institutions
POST/api/institutionsCreate a new institution
GET/api/institutions/{id}Get a specific institution
PUT/api/institutions/{id}Update an institution
DELETE/api/institutions/{id}Delete an institution

​
List All Institutions

curl -X GET "https://api.example.com/api/institutions" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

​
success
boolean
required
Indicates if the request was successful
​
message
string
required
Response message in Spanish
​
data
array
required
Array of institution objects
{
  "success": true,
  "message": "Instituciones listadas con éxito",
  "data": [
    {
      "id": 1,
      "nombre": "Instituto Educativo San Martín",
      "direccion": "Av. Principal 123, Lima",
      "telefono": "+51 1 234 5678",
      "email": "[email protected]",
      "logo_url": "https://example.com/logos/sanmartin.png",
      "anio_academico": 2026,
      "fecha_inicio": "2026-03-01",
      "fecha_fin": "2026-12-20",
      "created_at": "2026-03-05T10:30:00.000000Z",
      "updated_at": "2026-03-05T10:30:00.000000Z"
    }
  ]
}

​
Create Institution

curl -X POST "https://api.example.com/api/institutions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "nombre": "Colegio Nacional Bolognesi",
    "direccion": "Jr. Bolognesi 456, Arequipa",
    "telefono": "+51 54 123456",
    "email": "[email protected]",
    "logo_url": "https://example.com/logos/bolognesi.png",
    "anio_academico": 2026,
    "fecha_inicio": "2026-03-15",
    "fecha_fin": "2026-12-15"
  }'

​
Request Parameters

​
nombre
string
required
Name of the institution
​
direccion
string
required
Physical address of the institution
​
telefono
string
required
Contact phone number
​
email
string
required
Contact email address
​
logo_url
string
URL to the institution’s logo image. Can be null.
​
anio_academico
integer
required
Academic year (e.g., 2026). Must be a valid year number.
​
fecha_inicio
date
required
Academic year start date in YYYY-MM-DD format
​
fecha_fin
date
required
Academic year end date in YYYY-MM-DD format

​
Response

{
  "success": true,
  "message": "Institución creada con éxito",
  "data": {
    "id": 2,
    "nombre": "Colegio Nacional Bolognesi",
    "direccion": "Jr. Bolognesi 456, Arequipa",
    "telefono": "+51 54 123456",
    "email": "[email protected]",
    "logo_url": "https://example.com/logos/bolognesi.png",
    "anio_academico": 2026,
    "fecha_inicio": "2026-03-15",
    "fecha_fin": "2026-12-15",
    "created_at": "2026-03-05T11:15:00.000000Z",
    "updated_at": "2026-03-05T11:15:00.000000Z"
  }
}

​
Get Institution

curl -X GET "https://api.example.com/api/institutions/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Path Parameters

​
id
integer
required
The unique identifier of the institution

​
Response

{
  "success": true,
  "message": "Institución obtenida con éxito",
  "data": {
    "id": 1,
    "nombre": "Instituto Educativo San Martín",
    "direccion": "Av. Principal 123, Lima",
    "telefono": "+51 1 234 5678",
    "email": "[email protected]",
    "logo_url": "https://example.com/logos/sanmartin.png",
    "anio_academico": 2026,
    "fecha_inicio": "2026-03-01",
    "fecha_fin": "2026-12-20",
    "created_at": "2026-03-05T10:30:00.000000Z",
    "updated_at": "2026-03-05T10:30:00.000000Z"
  }
}

​
Update Institution

curl -X PUT "https://api.example.com/api/institutions/1" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "nombre": "Instituto Educativo San Martín de Porres",
    "direccion": "Av. Principal 123, Lima",
    "telefono": "+51 1 234 5679",
    "email": "[email protected]",
    "logo_url": "https://example.com/logos/sanmartin-new.png",
    "anio_academico": 2026,
    "fecha_inicio": "2026-03-01",
    "fecha_fin": "2026-12-20"
  }'

​
Path Parameters

​
id
integer
required
The unique identifier of the institution to update

​
Request Parameters

All parameters from the Create endpoint apply. You can send partial updates.
​
nombre
string
required
Name of the institution
​
direccion
string
required
Physical address of the institution
​
telefono
string
required
Contact phone number
​
email
string
required
Contact email address
​
logo_url
string
URL to the institution’s logo image
​
anio_academico
integer
required
Academic year number
​
fecha_inicio
date
required
Academic year start date (YYYY-MM-DD)
​
fecha_fin
date
required
Academic year end date (YYYY-MM-DD)

​
Response

{
  "success": true,
  "message": "Institución actualizada con éxito",
  "data": {
    "id": 1,
    "nombre": "Instituto Educativo San Martín de Porres",
    "direccion": "Av. Principal 123, Lima",
    "telefono": "+51 1 234 5679",
    "email": "[email protected]",
    "logo_url": "https://example.com/logos/sanmartin-new.png",
    "anio_academico": 2026,
    "fecha_inicio": "2026-03-01",
    "fecha_fin": "2026-12-20",
    "created_at": "2026-03-05T10:30:00.000000Z",
    "updated_at": "2026-03-05T14:20:00.000000Z"
  }
}

​
Delete Institution

curl -X DELETE "https://api.example.com/api/institutions/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Path Parameters

​
id
integer
required
The unique identifier of the institution to delete

​
Response

{
  "success": true,
  "message": "Institución eliminada con éxito",
  "data": null
}
Deleting an institution will cascade delete all associated users and registrations due to foreign key constraints.

Build docs developers (and LLMs) love

Get started for freeTalk to us