School Onboarding API

The guided page at kralis.app/onboard uses the public Kralis GraphQL onboarding operations. They do not require an existing user because they create the first school and administrator account.

School onboarding is available through GraphQL only. There is no REST onboarding equivalent.

Public operations

Operation	Kind	Purpose
`schoolAcronymSuggestion`	Query	Suggest a valid, currently available acronym from a school name
`schoolAcronymAvailability`	Query	Normalize, validate, and check a proposed acronym
`onboardSchool`	Mutation	Atomically create the school and its initial administrator

These operations may be called anonymously, but they cannot be combined in one request with protected operations. Public request limits still apply.

Suggest an acronym

query SuggestSchoolAcronym($schoolName: String!) {
  schoolAcronymSuggestion(schoolName: $schoolName)
}

{
  "schoolName": "North Star Academy"
}

Suggestions are conveniences, not reservations. Check the final value immediately before submission and still handle an availability error from onboardSchool.

Check an acronym

query CheckSchoolAcronym($schoolAcronym: String!) {
  schoolAcronymAvailability(schoolAcronym: $schoolAcronym) {
    schoolAcronym
    available
    reason
  }
}

{
  "schoolAcronym": "northstar"
}

The returned acronym is normalized. Display reason when available is false.

Create the school

mutation OnboardSchool($input: OnboardSchoolInput!) {
  onboardSchool(input: $input) {
    school {
      pk
      schoolName
      schoolAcronym
      schoolEmail
      schoolPhone
    }
    adminId
    adminPin
    accessCode
  }
}

{
  "input": {
    "schoolName": "North Star Academy",
    "schoolAcronym": "northstar",
    "adminPin": "A_STRONG_INITIAL_SECRET",
    "schoolEmail": "admin@northstar.example",
    "schoolPhone": "+2348000000000",
    "schoolMotto": "Learn and lead",
    "schoolAddress": "1 Learning Road",
    "schoolCity": "Enugu",
    "schoolState": "Enugu",
    "schoolCountry": "Nigeria",
    "schoolCountryShortCode": "NG",
    "studentMaxAccount": 100,
    "billingCycle": "annually",
    "marketingPackage": "official",
    "channel": "other"
  }
}

School and administrator creation is atomic: a failure creating the administrator does not leave a partially onboarded school. A successful response returns the initial administrator ID and PIN once so the client can show them to the operator. Do not log, email through an untrusted service, or retain the PIN in analytics. accessCode is present only when onboarding starts a supported payment transaction. When it is null, continue to the success screen without opening a payment flow.

Validation errors

Onboarding validation uses a stable GraphQL error code and field details:

{
  "errors": [
    {
      "message": "Invalid Form Data: ...",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "fieldErrors": {
          "school_acronym": ["School acronym is unavailable."]
        }
      }
    }
  ]
}

Map fieldErrors to the corresponding controls and show the top-level message as a form summary. For a transport or unexpected server failure, keep the entered draft and offer a safe retry rather than submitting repeatedly in the background.

After onboarding

Use the returned adminId and adminPin with the GraphQL login mutation. Then complete years, terms, classes, users, permissions, modules, and billing configuration in Kralis Web before relying on those records in a custom client. See Authentication and Developer Quickstart.

​Public operations

​Suggest an acronym

​Check an acronym

​Create the school

​Validation errors

​After onboarding

Public operations

Suggest an acronym

Check an acronym

Create the school

Validation errors

After onboarding