Student Integration Identifiers API

Student integration identifiers connect a Kralis student to the identifier used by an external system. They are useful when a partner does not use Kralis student IDs, or when an external result workbook must be matched back to Kralis records. The identifier belongs to the active school. It does not change the Kralis student’s name, username, class, or academic records.

Endpoint and authorization

Send the operations to the Kralis GraphQL API. Authenticate first and include the access token as described in Authentication. Every operation is evaluated against the authenticated user’s active school. The query requires the identifier view permission. Identifier mutations also require the corresponding add, change, or delete permission. Kralis Web currently exposes identifier management to authorized school administrators and deans; API clients should handle permission errors rather than assuming that a visible control grants access. Use GraphiQL to confirm the current schema, enum values, and generated filter argument names before shipping a client.

Supported integrations

The integration value is a stable machine key:

GraphQL enum	Stored key	Use
`ESMOE`	`esmoe`	Enugu State Ministry of Education workflows
`CDE`	`cde`	Catholic Diocese of Enugu Education Board workflows
`KLAPP`	`klapp`	Klapp school data integration

The GraphQL enum is uppercase even though the stored key is lowercase. Use the enum value in GraphQL variables.

Identifier fields

type StudentIntegrationIdentifierType {
  id: ID!
  pk: ID!
  student: StudentType!
  integration: CoreStudentIntegrationIdentifierIntegrationChoices!
  year: YearType
  externalId: String!
  externalName: String!
  metadata: JSONString!
}

externalName is retained as supplied by the partner. It is reference data, not a replacement for the Kralis name. metadata is an optional JSON object for integration-specific details.

Year behavior

yearId is optional in mutation input, and year_Id is the generated filter argument on the root connection.

A null year creates a yearless identifier that can be reused across academic years.
A year-specific identifier applies to one academic year.
A student can have one identifier per integration and year scope.
An external ID is unique within a school, integration, and year scope.
A nested student query with yearId returns the selected-year identifier first and can fall back to the yearless identifier.
The root studentIntegrationIdentifiers query filters the stored rows; it does not apply the nested fallback rule.

ESMOE registration numbers are currently treated as stable across academic years, so ESMOE synchronization normally creates yearless identifiers even though the Annual year is used to load the students for the workflow.

Query all identifiers

The root connection supports Relay pagination, generated Django-filter arguments, and a search that checks external IDs, external names, usernames, and student name fields.

query StudentIntegrationIdentifiers(
  $integration: CoreStudentIntegrationIdentifierIntegrationChoices
  $yearId: ID
  $studentIds: [ID!]
  $search: String
  $first: Int!
  $after: String
) {
  studentIntegrationIdentifiers(
    integration: $integration
    year_Id: $yearId
    student_In: $studentIds
    search: $search
    first: $first
    after: $after
  ) {
    totalCount
    edges {
      cursor
      node {
        id
        pk
        integration
        externalId
        externalName
        year { id pk yearName }
        student {
          pk
          userPtr { username fullName }
        }
        metadata
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Example variables:

{
  "integration": "ESMOE",
  "yearId": null,
  "studentIds": ["student-id-1", "student-id-2"],
  "search": "263098",
  "first": 50,
  "after": null
}

student_In accepts multiple student IDs. Use student when filtering for one student. The generated connection also exposes exact and text filter variants for supported fields, including id, externalId, externalName, student__user_ptr__id, and year_Id; confirm exact generated names in GraphiQL because Django-filter converts model lookups to GraphQL argument names. Example response:

{
  "data": {
    "studentIntegrationIdentifiers": {
      "totalCount": 1,
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "id": "U3R1ZGVudEludGVncmF0aW9uSWRlbnRpZmllclR5cGU6MQ==",
            "pk": "1",
            "integration": "ESMOE",
            "externalId": "26309843317240",
            "externalName": "Ozonwama chiamaka",
            "year": null,
            "student": {
              "pk": "student-id-1",
              "userPtr": {
                "username": "stu-123@school",
                "fullName": "Chiamaka Ozonwama"
              }
            },
            "metadata": "{\"source\":\"sync\"}"
          }
        }
      ],
      "pageInfo": { "hasNextPage": false, "endCursor": "…" }
    }
  }
}

Request id and pk for identifier records. Use endCursor for the next page and merge pages by a stable identifier; see Errors and Pagination.

Query identifiers through a student

Use the nested field when loading a student together with the identifier needed by a workflow. The integration and yearId arguments narrow the result, while the resolver prefers a selected-year row and falls back to a yearless row.

query StudentWithEsmoeIdentifier($studentId: ID!, $yearId: ID) {
  students(userPtr_Id: $studentId, first: 1) {
    edges {
      node {
        pk
        userPtr { username fullName }
        integrationIdentifiers(
          integration: ESMOE
          yearId: $yearId
          first: 10
        ) {
          edges {
            node {
              id
              pk
              externalId
              externalName
              year { pk yearName }
              metadata
            }
          }
        }
      }
    }
  }
}

For a student account ID, userPtr_Id is the student filter used by the students connection. The student object exposes its Node id and database pk for follow-up operations.

Input objects

Create, update, and upsert use StudentIntegrationIdentifierInput:

input StudentIntegrationIdentifierInput {
  studentId: ID!
  integration: IntegrationKey!
  yearId: ID
  externalId: String!
  externalName: String
  metadata: GenericScalar
}

Replacement uses a separate input because changing the student assignment or external ID is an explicit correction:

input ReplaceStudentIntegrationIdentifierInput {
  identifierId: ID!
  studentId: ID!
  externalId: String!
  externalName: String
  metadata: GenericScalar
}

For JSON variables, send metadata as an object. On update and upsert, omitting metadata preserves the existing metadata. Supplying it replaces the stored metadata object.

Create one identifier

Use create for a new mapping. It rejects invalid school relations, duplicate scoped mappings, unsupported integrations, and non-object metadata.

mutation CreateStudentIntegrationIdentifier(
  $input: StudentIntegrationIdentifierInput!
) {
  createStudentIntegrationIdentifier(input: $input) {
    identifier {
      id
      pk
      integration
      externalId
      externalName
      year { pk yearName }
      student { pk userPtr { username fullName } }
      metadata
    }
  }
}

{
  "input": {
    "studentId": "student-id-1",
    "integration": "ESMOE",
    "externalId": "26309843317240",
    "externalName": "Ozonwama chiamaka",
    "metadata": { "source": "manual" }
  }
}

Update one identifier

Update changes the selected identifier’s fields. It does not silently move a conflicting external identifier to another student; use the replacement mutation for reassignment.

mutation UpdateStudentIntegrationIdentifier(
  $id: ID!
  $input: StudentIntegrationIdentifierInput!
) {
  updateStudentIntegrationIdentifier(id: $id, input: $input) {
    identifier {
      id
      pk
      integration
      externalId
      externalName
      year { pk yearName }
      metadata
    }
  }
}

Upsert confirmed mappings in bulk

upsertStudentIntegrationIdentifiers is for confirmed mappings. It creates missing rows and updates an existing row for the same student, integration, and year scope. It returns separate counts.

mutation UpsertStudentIntegrationIdentifiers(
  $inputs: [StudentIntegrationIdentifierInput]!
) {
  upsertStudentIntegrationIdentifiers(inputs: $inputs) {
    createdCount
    updatedCount
    identifiers {
      id
      pk
      student { pk }
      integration
      externalId
      externalName
      year { pk yearName }
      metadata
    }
  }
}

Upsert rejects duplicate students or external IDs in one batch, and rejects attempts to change an existing student’s external ID or assign an already-used external ID to another student. Those cases require explicit replacement. Example bulk response:

{
  "data": {
    "upsertStudentIntegrationIdentifiers": {
      "createdCount": 1,
      "updatedCount": 2,
      "identifiers": [
        {
          "id": "…",
          "pk": "1",
          "student": { "pk": "student-id-1" },
          "integration": "ESMOE",
          "externalId": "26309843317240",
          "externalName": "Ozonwama chiamaka",
          "year": null,
          "metadata": "{\"source\":\"sync\"}"
        }
      ]
    }
  }
}

Replace identifier assignments

Use replaceStudentIntegrationIdentifiers after a user has confirmed a conflict. It atomically moves or changes the selected existing rows and prevents duplicate target assignments.

mutation ReplaceStudentIntegrationIdentifiers(
  $inputs: [ReplaceStudentIntegrationIdentifierInput]!
) {
  replaceStudentIntegrationIdentifiers(inputs: $inputs) {
    replacedCount
    identifiers {
      id
      pk
      student { pk userPtr { username fullName } }
      integration
      externalId
      externalName
      year { pk yearName }
      metadata
    }
  }
}

The replacement input contains the existing identifierId, the new studentId, and the external ID. The mutation preserves metadata unless a new metadata object is supplied. It is the safe path when an ESMOE registration number is already linked to Student A and a user confirms moving it to Student B.

Delete identifiers

Delete one row with deleteStudentIntegrationIdentifier:

mutation DeleteStudentIntegrationIdentifier($id: ID!) {
  deleteStudentIntegrationIdentifier(id: $id) {
    deleted
  }
}

Delete selected rows, optionally limited to one integration and year, with bulkDeleteStudentIntegrationIdentifiers:

mutation BulkDeleteStudentIntegrationIdentifiers(
  $integration: IntegrationKey!
  $yearId: ID
  $ids: [ID!]
) {
  bulkDeleteStudentIntegrationIdentifiers(
    integration: $integration
    yearId: $yearId
    ids: $ids
  ) {
    deletedCount
  }
}

When ids is supplied, only those school-scoped rows are deleted. Without ids, the mutation deletes all rows in the supplied integration and optional year scope, so clients should require an explicit confirmation before calling it.

Recommended client flow

Load only the active school’s students and paginate both student and identifier connections.
Prefer an existing identifier over name matching.
Treat suggested or fuzzy matches as reviewable, not automatically confirmed unless the workflow’s confidence rules allow it.
Use upsert for new or unchanged confirmed mappings.
Use replacement for an existing external ID that must move to another Kralis student.
Refetch after mutations so the UI reflects the authoritative school-scoped state.

For the operator-facing management workflow, see Student integration identifiers. For ESMOE-specific matching and workbook behavior, see the ESMOE integration guide.

​Endpoint and authorization

​Supported integrations

​Identifier fields

​Year behavior

​Query all identifiers

​Query identifiers through a student

​Input objects

​Create one identifier

​Update one identifier

​Upsert confirmed mappings in bulk

​Replace identifier assignments

​Delete identifiers

​Recommended client flow