Padrón

El padrón es el registro de titulares del sostenedor: estudiantes, apoderados, los vínculos entre ellos y las matrículas por año escolar. En esta página revisamos los endpoints que permiten a tu integración mantener ese padrón sincronizado con tu propio sistema, usando el referenceCode de cada titular como llave externa.

Todas las rutas de esta página cuelgan de la URL base https://app.edugoverna.com/api/partner/v1/organizations/:organizationId, donde :organizationId es la organización dueña del padrón (el colegio o registro con el que tu credencial tiene una conexión activa). La autenticación se describe en Autenticación y los alcances de conexión en Conexiones.

El modelo de padrón

El padrón se compone de cuatro entidades, todas escribibles por upsert:

Estudiante y apoderado son titulares (subjectType: "student" y "guardian"). Cada uno se identifica ante la API por su referenceCode, un código estable que tu sistema define — típicamente tu propio ID de alumno o apoderado. Un PUT sobre un referenceCode inexistente crea el titular; sobre uno existente, lo rectifica.
Vínculo (guardianship) conecta a un apoderado con un estudiante y declara qué autoridad tiene: consentir tratamiento general, consentir datos sensibles, ejercer derechos. Es único por par estudiante–apoderado.
Matrícula (enrollment) registra la situación de un estudiante en un año escolar concreto (curso, nivel, estado). Es única por estudiante y schoolYear.

Las lecturas del padrón devuelven una proyección parcial del titular, no el registro completo: la API Partner recibe nombres y contactos (Edugoverna necesita que puedas verificar a quién le pides consentimiento), pero el RUT viaja enmascarado (identifierType y last4, nunca el valor), la fecha de nacimiento no se devuelve, y los campos sensibles del perfil (hasSpecialNeeds, hasHealthAlerts, códigos internos) vuelven en null. Toda lectura queda registrada en la auditoría de la organización dueña.

Campos de identidad compartidos

Los PUT de estudiante y apoderado aceptan el mismo bloque de identidad:

Nombre
legalGivenNames
Tipo
string
Descripción
Nombres legales. Máximo 160 caracteres.
Nombre
legalFamilyNames
Tipo
string
Descripción
Apellidos legales. Máximo 160 caracteres.
Nombre
preferredName
Tipo
string
Descripción
Nombre social o de uso preferente. Máximo 160 caracteres.
Nombre
birthDate
Tipo
string
Descripción
Fecha de nacimiento en formato ISO (YYYY-MM-DD). Determina la banda etaria y con ella quién puede consentir. Se acepta en escritura pero no se devuelve en las lecturas de la API Partner.
Nombre
identifier
Tipo
object
Descripción
Identificador primario del titular: identifierType (por ejemplo "rut"), value, y opcionalmente normalizedValue y last4. Se cifra en reposo; las lecturas sólo devuelven identifierType y last4.
Nombre
contact
Tipo
object
Descripción
Contacto primario: contactType (típicamente "email" o "phone", que son los canales que Edugoverna normaliza y despacha), value, y opcionalmente label, normalizedValue e isNotificationEnabled. El upsert es por tipo: escribir un email no borra el teléfono existente, sólo le quita la marca de primario. Cambiar el valor reinicia la verificación del contacto.

GET/v1/organizations/:organizationId/directory/subjects

Listar sujetos del padrón

Devuelve una página de titulares del padrón con la proyección parcial descrita arriba.

Permiso requerido: partner.subjects.read · Alcance de conexión: subjects:read.

Este endpoint está pensado para consultas acotadas, no para exportar el padrón: como la proyección incluye valores de contacto, rige el control de lecturas masivas y una consulta cuyo total de coincidencias supere los 25 titulares se rechaza con 403 SUBJECT_BULK_READ_APPROVAL_REQUIRED. Usa el filtro referenceCode para resolver titulares puntuales; para recorrer grupos completos compartidos contigo está la lectura ofuscada de Campañas compartidas.

Si la conexión define la condición onlyActive en su alcance subjects:read, la lista excluye automáticamente a los titulares que no estén en estado active.

Parámetros de consulta opcionales

Nombre
subjectType
Tipo
string
Descripción
Filtra por tipo de titular: student o guardian.
Nombre
referenceCode
Tipo
string
Descripción
Devuelve únicamente el titular con ese código de referencia (a lo más un resultado).
Nombre
limit
Tipo
integer
Descripción
Tamaño de página. Por defecto 100, máximo 250.
Nombre
cursor
Tipo
string
Descripción
Cursor de la página anterior (meta.nextCursor). Ver Paginación.

Request

GET

/v1/.../directory/subjects

curl -G https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/directory/subjects \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -d referenceCode=EST-2026-0142

Response

{
  "subjects": [
    {
      "id": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
      "organizationId": "org_2f7a",
      "subjectType": "student",
      "referenceCode": "EST-2026-0142",
      "currentAgeBand": "under_14",
      "currentGeneralConsentAuthority": "guardian",
      "currentSensitiveConsentAuthority": "guardian",
      "status": "active",
      "activeGuardianCount": 1,
      "legalGivenNames": "Martina",
      "legalFamilyNames": "Rojas Pino",
      "preferredName": null,
      "birthDate": null,
      "identifierType": "rut",
      "identifierValue": null,
      "identifierNormalizedValue": null,
      "identifierLast4": "435-2",
      "contactType": "email",
      "contactValue": "apoderado@familia.cl",
      "contactIsNotificationEnabled": true,
      "studentProfile": {
        "currentGradeLevel": "5° Básico",
        "currentEnrollmentYear": 2026,
        "schoolStudentCode": null,
        "nationalStudentNumber": null,
        "hasSpecialNeeds": null,
        "hasHealthAlerts": null,
        "metadata": null
      },
      "guardianProfile": null
      // ...
    }
  ],
  "meta": {
    "projection": {
      "identity": "basic",
      "contact": "full",
      "identifier": "metadata",
      "studentProfile": "redacted",
      "guardianProfile": "redacted"
    },
    "filteredRestrictedCount": 0,
    "totalMatchedCount": 1,
    "nextCursor": null
  }
}

PUT/v1/organizations/:organizationId/directory/students/:referenceCode

Upsert de un estudiante

Crea o rectifica al estudiante identificado por :referenceCode. Todos los campos del cuerpo son opcionales: en una rectificación sólo se tocan los campos presentes.

Permiso requerido: partner.subjects.write · Alcance de conexión: subjects:write.

Si el referenceCode ya pertenece a un apoderado, la llamada falla con 409 PARTNER_SUBJECT_TYPE_CONFLICT. Un RUT inválido o ya asignado a otro titular se rechaza antes de escribir nada. Cada rectificación deja un evento de auditoría partner_synced sobre el titular en la organización dueña.

Atributos opcionales

Además del bloque de identidad:

Nombre
studentProfile
Tipo
object
Descripción
Perfil académico: schoolStudentCode, nationalStudentNumber, currentGradeLevel, currentEnrollmentYear (2000–2100), hasSpecialNeeds, hasHealthAlerts y metadata (objeto libre).

La respuesta es el estudiante con la misma proyección parcial del listado.

Request

PUT

/v1/.../directory/students/EST-2026-0142

curl -X PUT https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/directory/students/EST-2026-0142 \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "legalGivenNames": "Martina",
    "legalFamilyNames": "Rojas Pino",
    "birthDate": "2015-04-12",
    "identifier": { "identifierType": "rut", "value": "25.678.435-2" },
    "studentProfile": { "currentGradeLevel": "5° Básico", "currentEnrollmentYear": 2026 }
  }'

Response

{
  "id": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
  "subjectType": "student",
  "referenceCode": "EST-2026-0142",
  "status": "active",
  "legalGivenNames": "Martina",
  "legalFamilyNames": "Rojas Pino",
  "birthDate": null,
  "identifierType": "rut",
  "identifierLast4": "435-2",
  "studentProfile": {
    "currentGradeLevel": "5° Básico",
    "currentEnrollmentYear": 2026,
    "hasSpecialNeeds": null,
    "hasHealthAlerts": null
  }
  // ...
}

PUT/v1/organizations/:organizationId/directory/guardians/:referenceCode

Upsert de un apoderado

Crea o rectifica al apoderado identificado por :referenceCode. La semántica es idéntica al upsert de estudiante — mismos campos de identidad, mismo 409 PARTNER_SUBJECT_TYPE_CONFLICT si el código pertenece a un estudiante, mismo evento de auditoría partner_synced en rectificaciones.

Permiso requerido: partner.subjects.write · Alcance de conexión: subjects:write.

Atributos opcionales

Además del bloque de identidad:

Nombre
guardianProfile
Tipo
object
Descripción
Perfil del apoderado: relationshipLabel (máx. 80), emergencyPriority (0–10), canPickUpStudent y metadata.

El contacto primario del apoderado es lo que el motor de consentimientos usa para despachar solicitudes cuando el estudiante es menor, así que conviene mantenerlo al día.

Request

PUT

/v1/.../directory/guardians/APO-889

curl -X PUT https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/directory/guardians/APO-889 \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "legalGivenNames": "Carolina",
    "legalFamilyNames": "Pino Soto",
    "contact": { "contactType": "email", "value": "carolina.pino@familia.cl" },
    "guardianProfile": { "relationshipLabel": "Madre" }
  }'

Response

{
  "id": "5d2a8c3b-77e1-4b0e-9f1d-3c4e5f6a7b8c",
  "subjectType": "guardian",
  "referenceCode": "APO-889",
  "status": "active",
  "legalGivenNames": "Carolina",
  "legalFamilyNames": "Pino Soto",
  "contactType": "email",
  "contactValue": "carolina.pino@familia.cl",
  "guardianProfile": {
    "relationshipLabel": "Madre",
    "emergencyPriority": 0,
    "canPickUpStudent": true,
    "metadata": null
  }
  // ...
}

PUT/v1/organizations/:organizationId/directory/guardianships/:studentReferenceCode/:guardianReferenceCode

Upsert de un vínculo

Crea o actualiza el vínculo entre el estudiante y el apoderado identificados en la ruta. Ambos titulares deben existir previamente; si alguno no existe la llamada falla con 404 PARTNER_SUBJECT_NOT_FOUND, y si un código pertenece al tipo equivocado, con 409 PARTNER_SUBJECT_TYPE_CONFLICT.

Permiso requerido: partner.guardianships.write · Alcance de conexión: guardianships:write.

En una actualización, los campos omitidos conservan su valor anterior (relationshipType es el único siempre requerido). Las actualizaciones dejan un evento de auditoría updated sobre el vínculo.

Atributos requeridos

Nombre
relationshipType
Tipo
string
Descripción
Tipo de relación (por ejemplo "madre", "padre", "tutor_legal"). Entre 2 y 80 caracteres.

Atributos opcionales

Nombre
authorityScope
Tipo
string
Descripción
Alcance de la autoridad. Por defecto "full".
Nombre
canConsentGeneral
Tipo
boolean
Descripción
Puede otorgar consentimiento para tratamiento general. Por defecto true.
Nombre
canConsentSensitive
Tipo
boolean
Descripción
Puede otorgar consentimiento sobre datos sensibles. Por defecto true.
Nombre
canExerciseRights
Tipo
boolean
Descripción
Puede ejercer derechos en nombre del estudiante. Por defecto true.
Nombre
requiresCoSignature
Tipo
boolean
Descripción
Exige co-firma de otro apoderado. Por defecto false.
Nombre
priority
Tipo
integer
Descripción
Prioridad del apoderado (0–100). Por defecto 0.
Nombre
status
Tipo
string
Descripción
Estado del vínculo. Por defecto "active".
Nombre
validFrom
Tipo
timestamp
Descripción
Inicio de vigencia del vínculo.
Nombre
validTo
Tipo
timestamp
Descripción
Fin de vigencia del vínculo.
Nombre
notes
Tipo
string
Descripción
Notas libres. Máximo 1000 caracteres.

Request

PUT

/v1/.../guardianships/EST-2026-0142/APO-889

curl -X PUT https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/directory/guardianships/EST-2026-0142/APO-889 \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{ "relationshipType": "madre", "canConsentSensitive": true }'

Response

{
  "id": "1b7d9e2f-4a6c-4d8e-b0f1-2c3d4e5f6a7b",
  "organizationId": "org_2f7a",
  "studentSubjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
  "guardianSubjectId": "5d2a8c3b-77e1-4b0e-9f1d-3c4e5f6a7b8c",
  "relationshipType": "madre",
  "authorityScope": "full",
  "canConsentGeneral": true,
  "canConsentSensitive": true,
  "canExerciseRights": true,
  "requiresCoSignature": false,
  "priority": 0,
  "status": "active",
  "validFrom": null,
  "validTo": null,
  "notes": null,
  "createdAt": "2026-03-02T14:11:09.000Z",
  "updatedAt": "2026-08-25T12:30:00.000Z"
}

PUT/v1/organizations/:organizationId/directory/students/:studentReferenceCode/enrollments/:schoolYear

Upsert de una matrícula

Crea o actualiza la matrícula del estudiante para el año escolar :schoolYear (entero entre 2000 y 2100; un valor fuera de rango responde 422 VALIDATION_ERROR). La matrícula es única por estudiante y año, así que repetir la llamada actualiza la misma fila.

Permiso requerido: partner.enrollments.write · Alcance de conexión: enrollments:write.

Si el :studentReferenceCode no existe o pertenece a un apoderado, la llamada falla con 404 PARTNER_SUBJECT_NOT_FOUND o 409 PARTNER_SUBJECT_TYPE_CONFLICT respectivamente.

Atributos opcionales

Nombre
enrollmentStatus
Tipo
string
Descripción
Estado de la matrícula. Por defecto "enrolled".
Nombre
gradeLevel
Tipo
string
Descripción
Nivel (por ejemplo "5° Básico").
Nombre
courseCode
Tipo
string
Descripción
Código del curso (por ejemplo "5B").
Nombre
courseName
Tipo
string
Descripción
Nombre del curso.
Nombre
enrollmentSource
Tipo
string
Descripción
Origen del dato de matrícula en tu sistema.
Nombre
admittedAt
Tipo
timestamp
Descripción
Fecha de admisión. Por defecto, el momento de la creación.
Nombre
withdrawnAt
Tipo
timestamp
Descripción
Fecha de retiro, si corresponde.
Nombre
externalStudentId
Tipo
string
Descripción
Identificador del estudiante en el sistema de origen.
Nombre
metadata
Tipo
object
Descripción
Objeto libre con datos adicionales.

Request

PUT

/v1/.../students/EST-2026-0142/enrollments/2026

curl -X PUT https://app.edugoverna.com/api/partner/v1/organizations/org_2f7a/directory/students/EST-2026-0142/enrollments/2026 \
  -H "Authorization: Bearer {keyId}.{secret}" \
  -H "Content-Type: application/json" \
  -d '{ "gradeLevel": "5° Básico", "courseCode": "5B", "courseName": "5° Básico B" }'

Response

{
  "id": "7e5f3a1c-9b8d-4c2e-a6f0-1d2e3f4a5b6c",
  "organizationId": "org_2f7a",
  "studentSubjectId": "9c1f6d1e-1c9d-4f6a-9a44-1f2ab5c0d9e1",
  "schoolYear": 2026,
  "enrollmentStatus": "enrolled",
  "gradeLevel": "5° Básico",
  "courseCode": "5B",
  "courseName": "5° Básico B",
  "enrollmentSource": null,
  "admittedAt": "2026-03-01T12:00:00.000Z",
  "withdrawnAt": null,
  "externalStudentId": null,
  "createdAt": "2026-03-01T12:00:00.000Z",
  "updatedAt": "2026-08-25T12:30:00.000Z"
}