Update Student

The updateStudent mutation applies a partial update to a student’s basic profile and admin tags in the current school.

Only the input keys you provide are applied — omitted keys leave the corresponding field unchanged. All writes are absolute sets, so the mutation is idempotent and safe to retry. Updatable users are those holding the student role in the school; teaching assistants without the student role, and unknown or out-of-school IDs, return a not-found error.

Email is intentionally not updatable through this mutation — it is the idempotency key used elsewhere in the Admin API (for example createStudent).

Required scope

Requires one of:

students:write
members:write

Signature

updateStudent(
  id: String!                    # Required. ID of the student to update.
  input: AdminStudentUpdateInput! # Required. Partial-update fields (see below).
): AdminUpdateStudentPayload!

input AdminStudentUpdateInput {
  name: String          # Omit to leave unchanged. Explicit null or a blank string is rejected.
  phoneNumber: String   # Omit to leave unchanged; pass null to clear it. Normalized with a TW default country code.
  tags: [String!]       # Replaces the entire admin-tag list. Empty array clears all; explicit null is a no-op.
}

type AdminUpdateStudentPayload {
  student: AdminUser    # The updated student, null if the update failed.
  errors: [String!]     # Validation errors, if any occurred during the update.
}

The payload type name is auto-generated as <MutationName>Payload from the mutation’s graphql_name. The mutation declares graphql_name "AdminUpdateStudent", so the payload is AdminUpdateStudentPayload.

Arguments

`id` (required)

The ID of the student to update. Must reference a user holding the student role in the current school. Unknown IDs, users from another school, and users without the student role all return STUDENT-005.

`input` (required)

An AdminStudentUpdateInput object. Every field is optional; the mutation applies only the keys that are present.

name — Display name. Omit to leave unchanged. Because the underlying user record has no name-presence validation, an explicit null or a blank string is rejected with STUDENT-003 rather than silently blanking the display name.
phoneNumber — Phone number. Omit to leave unchanged; pass null to clear it. The value is normalized with a Taiwan default country code and echoed back normalized.
tags — Admin tags. Replaces the entire list, so pass every tag each time. An empty array clears all admin tags; an explicit null is a no-op (same as omitting the key). Individual tags must be non-blank and must not contain commas — a comma-containing tag is rejected with STUDENT-007. Read the current list from the AdminUser.tags field before writing. System-managed tags are never touched.

Tags are access-granting. Admin tags can gate access to tag-restricted consulting services, so writing tags is effectively an access-control operation. Always read the existing tags before replacing the list.

Payload

AdminUpdateStudentPayload returns:

student — The updated AdminUser, or null when the update failed on a validation error (in which case errors is populated).
errors — A list of validation messages when a recoverable validation failure occurred, otherwise null.

Note the two failure shapes: recoverable validation failures return { student: null, errors: [...] } in the payload, while the coded errors below are raised into the top-level GraphQL errors array.

Error codes

Code	Meaning
`STUDENT-003`	`name` was provided as an explicit `null` or a blank string. A student must keep a display name.
`STUDENT-005`	No matching student found — unknown ID, a user outside the current school, or a user without the `student` role.
`STUDENT-006`	Catch-all update failure. Includes the underlying error message.
`STUDENT-007`	A tag value is blank or contains a comma. The message includes the offending value.

Errors are returned in the standard GraphQL errors array. The error code is in extensions.error.code.

Example: update name and phone number

mutation {
  updateStudent(
    id: "abc-123"
    input: { name: "Alice Liddell", phoneNumber: "+886912345678" }
  ) {
    student {
      id
      name
      phoneNumber
    }
    errors
  }
}

{
  "data": {
    "updateStudent": {
      "student": {
        "id": "abc-123",
        "name": "Alice Liddell",
        "phoneNumber": "+886912345678"
      },
      "errors": null
    }
  }
}

Example: replace admin tags

mutation {
  updateStudent(
    id: "abc-123"
    input: { tags: ["vip", "cohort-2026"] }
  ) {
    student {
      id
      tags
    }
    errors
  }
}

{
  "data": {
    "updateStudent": {
      "student": {
        "id": "abc-123",
        "tags": ["vip", "cohort-2026"]
      },
      "errors": null
    }
  }
}

For more information about the Teachify Admin API, please refer to the API Overview.