> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kralis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# School Onboarding API

> Suggest and validate school acronyms, create a school, and receive its initial administrator credentials through GraphQL.

The guided page at [kralis.app/onboard](https://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.

<Note>
  School onboarding is available through GraphQL only. There is no REST
  onboarding equivalent.
</Note>

```mermaid theme={null}
flowchart LR
    A[Enter school name] --> B[Suggest acronym]
    B --> C[Check availability]
    C --> D[Submit school details]
    D --> E[Create school and administrator]
    E --> F[Sign in with login]
    F --> G[Configure school in Kralis Web]
```

## 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

```graphql theme={null}
query SuggestSchoolAcronym($schoolName: String!) {
  schoolAcronymSuggestion(schoolName: $schoolName)
}
```

```json theme={null}
{
  "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

```graphql theme={null}
query CheckSchoolAcronym($schoolAcronym: String!) {
  schoolAcronymAvailability(schoolAcronym: $schoolAcronym) {
    schoolAcronym
    available
    reason
  }
}
```

```json theme={null}
{
  "schoolAcronym": "northstar"
}
```

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

## Create the school

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/developers/authentication) and [Developer Quickstart](/developers/getting-started).