Sujetos del padrón

El padrón es el corazón del producto: cada persona cuyos datos trata el colegio es un titular (data_subject) — estudiante, apoderado, funcionario u otro. Alrededor del titular orbitan los vínculos de apoderado (guardianship), las Generaciones (student_cohort, la promoción que avanza junta) y los Cursos y segmentos (student_segment; un Curso es un segmento con kind: "course"). Esta página cubre las cinco superficies, empezando por la regla que las gobierna a todas: la proyección de lectura.

La vista de producto del padrón está en Padrón.

Qué ves depende de tu proyección

Cada respuesta de lectura de titulares se filtra por la escalera de permisos subjects.read.* de tu API key, y la proyección aplicada viaja en meta.projection para que tu integración no tenga que adivinar:

• Los listados nunca son sensibles. GET /data-subjects degrada la proyección al nivel de nómina: identidad a lo más basic (nombres sí, fecha de nacimiento/dirección/RUT no) y contacto a lo más masked. Por eso listar no exige aprobación de lectura masiva ni escribe eventos de acceso sensible.
• El registro completo vive en el detalle. Sólo GET /data-subjects/:subjectId entrega la proyección plena de tu key; una lectura con proyección sensible queda registrada en el historial de accesos.
• directory no entrega ningún nombre. A ese tier los campos de identidad llegan en null y el titular se referencia por referenceCode.

Los campos que la proyección oculta llegan como null, nunca desaparecen del cuerpo: la forma de la respuesta es estable entre tiers.

Listar titulares

curl -G "https://app.edugoverna.com/api/data-subjects" \
  -H "x-api-key: {tu_api_key}" \
  -d type=student -d limit=50

{
  "dataSubjects": [
    {
      "id": "3f6f0a2e-…",
      "subjectType": "student",
      "referenceCode": "EST-2026-0412",
      "status": "active",
      "currentAgeBand": "minor_14_17",
      "currentGeneralConsentAuthority": "guardian",
      "activeGuardianCount": 2,
      "legalGivenNames": "Martina",
      "legalFamilyNames": "Rojas Fuentes",
      "preferredName": null,
      "birthDate": null,
      "contactType": "email",
      "contactValue": null,
      "contactMaskedValue": "a•••o@example.com",
      "identifierType": "rut",
      "identifierValue": null,
      "identifierLast4": "6789",
      "studentGroupSummary": {
        "activeCohort": { "name": "Generación 2030" },
        "segments": [{ "name": "1°A" }]
      }
      // …
    }
  ],
  "meta": {
    "filteredRestrictedCount": 0,
    "totalMatchedCount": 412,
    "nextCursor": "eyJz…",
    "projection": {
      "identity": "basic",
      "contact": "masked",
      "identifier": "metadata",
      "studentProfile": "redacted",
      "guardianProfile": "redacted"
    }
  }
}

El detalle (GET /data-subjects/:subjectId) responde { dataSubject, meta } con la misma forma pero bajo la proyección completa de tu key: con identity_sensitive aparecen birthDate, dirección y el RUT en claro; con contact_full, los valores de contacto descifrados en contacts[] y primaryContact.

Crear un titular

curl -X POST "https://app.edugoverna.com/api/data-subjects" \
  -H "x-api-key: {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "student",
    "legalGivenNames": "Martina",
    "legalFamilyNames": "Rojas Fuentes",
    "birthDate": "2012-04-18",
    "identifier": { "identifierType": "rut", "value": "23456789-6", "isPrimary": true },
    "contacts": [{ "contactType": "email", "value": "apoderado@example.com" }],
    "primaryContactType": "email"
  }'

El resto del ciclo de vida del titular

Apoderados

curl -G "https://app.edugoverna.com/api/guardianships" \
  -H "x-api-key: {tu_api_key}" \
  -d studentSubjectId=3f6f0a2e-…

{
  "guardianships": [
    {
      "id": "gd12…",
      "studentSubjectId": "3f6f0a2e-…",
      "guardianSubjectId": "8a4c…",
      "relationshipType": "madre",
      "authorityScope": "full",
      "canConsentGeneral": true,
      "canConsentSensitive": true,
      "canExerciseRights": true,
      "priority": 1,
      "status": "active",
      "provenance": "administrative",
      "studentSummary": { "referenceCode": "EST-2026-0412", "displayName": "Martina Rojas" },
      "guardianSummary": { "referenceCode": "APO-2026-0311", "displayName": "Carolina Fuentes" }
    }
  ],
  "meta": { "filteredRestrictedCount": 0 }
}

Los documentos que acreditan la autoridad de un apoderado (resoluciones, poderes) se gestionan en /records/authority-documents.

Generaciones

La Generación es la promoción que avanza junta por los años escolares. Lectura con students.read, escritura con students.write.

Cursos y segmentos

curl -G "https://app.edugoverna.com/api/student-segments" \
  -H "x-api-key: {tu_api_key}" \
  -d kind=course

{
  "studentSegments": [
    {
      "id": "5b2c…",
      "name": "1°A",
      "kind": "course",
      "type": "fixed",
      "courseSchoolYear": 2026,
      "courseGradeLevel": "1° básico",
      "courseCode": "1A",
      "status": "active",
      "activeMemberCount": 32,
      "filterDefinition": null
    }
  ]
}

Perfil del colegio

La organización dueña de la API key, con su perfil escolar. Lectura con schools.read; POST /schools/current (con schools.write) crea o actualiza el perfil (201 la primera vez, 200 después).

{
  "organization": {
    "id": "org_…",
    "name": "Colegio Andes",
    "slug": "colegio-andes",
    "logo": "/api/public/branding/logos/org_…?v=…",
    "brandColor": "#D64545"
  },
  "schoolProfile": {
    "legalName": "Colegio Andes SpA",
    "schoolCode": "12345-5",
    "schoolType": "school",
    "educationLevels": ["basica", "media"],
    "commune": "Providencia",
    "countryCode": "CL",
    "privacyContactEmail": "privacidad@colegioandes.cl"
    // …
  }
}

Para poblar el padrón masivamente desde una planilla, sigue con Importaciones.