> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/managebac/public-rest-apis/v2p0/students.md).

# Students

Students are child users who use ManageBac to learn

## Update Student Avatar

> Updates or replaces a student's avatar image. Accepts either a remote URL\
> or a direct file upload.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}},"NotFound":{"type":"object","description":"Returned when the requested resource cannot be found by the given ID.","properties":{"error":{"type":"string","description":"A human-readable message indicating which resource could not be found, including the model name and the ID that was looked up."}}}}},"paths":{"/v2p0/students/{id}/avatar":{"put":{"summary":"Update Student Avatar","operationId":"updateStudentAvatar","tags":["Students"],"description":"Updates or replaces a student's avatar image. Accepts either a remote URL\nor a direct file upload.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}},"422":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"base":{"type":"array","items":{"type":"string"}}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"avatar":{"type":"object","anyOf":[{"properties":{"remote_file_url":{"type":"string","description":"Avatar URL to upload"}},"required":["remote_file_url"]},{"properties":{"file":{"type":"string","format":"binary","description":"Avatar file data"}},"required":["file"]}]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"avatar":{"type":"object","anyOf":[{"properties":{"remote_file_url":{"type":"string","description":"Avatar URL to upload"}},"required":["remote_file_url"]},{"properties":{"file":{"type":"string","format":"binary","description":"Avatar file data"}},"required":["file"]}]}}}}},"required":true,"description":"Avatar params"}}}}}
```

## Delete Student Avatar

> Deletes a student's avatar image. This action cannot be undone.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}},"NotFound":{"type":"object","description":"Returned when the requested resource cannot be found by the given ID.","properties":{"error":{"type":"string","description":"A human-readable message indicating which resource could not be found, including the model name and the ID that was looked up."}}}}},"paths":{"/v2p0/students/{id}/avatar":{"delete":{"summary":"Delete Student Avatar","operationId":"deleteStudentAvatar","tags":["Students"],"description":"Deletes a student's avatar image. This action cannot be undone.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}}}}
```

## Get all Students

> Retrieves a paginated list of all students in the school. Returns personal details, program information,\
> and any school-defined custom field values for each student. Results can be filtered by archive status,\
> enrollment status, year group, homeroom advisor, modification date, deletion date, or a search query.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"parameters":{"idsQueryParam":{"name":"ids[]","in":"query","description":"Return only records with the given IDs.","required":false,"allowReserved":true,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}}},"schemas":{"Student":{"anyOf":[{"$ref":"#/components/schemas/PersonalInformation"},{"type":"object","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this student in ManageBac. Read-only."},"sb_id":{"type":"string","description":"External identifier from SchoolsBuddy, if the school uses that integration. May be null."},"oa_id":{"type":"string","description":"External identifier from OpenApply, if the school uses that integration. May be null."},"graduated_on":{"type":"string","description":"Date when the student graduated, in yyyy-mm-dd format. Only present for students with a \"graduated\" status. Null for active or withdrawn students.\n"},"withdrawn_on":{"type":"string","description":"Date when the student was withdrawn from the school, in yyyy-mm-dd format. Only present for students with a \"withdrawn\" status. Null for active or graduated students.\n"},"student_id":{"type":"string","description":"The school’s own unique identifier for this student (e.g. a student number). Set by the school, not by ManageBac."},"homeroom_advisor_id":{"type":"integer","description":"ManageBac ID of the teacher assigned as this student’s homeroom advisor (tutor). Null if not assigned."},"year_group_id":{"type":"integer","description":"ManageBac ID of the year group this student is currently enrolled in."},"graduating_year":{"type":"integer","description":"The calendar year in which the student is expected to graduate. This is a four-digit year, not a date."},"parent_ids":{"type":"array","description":"ManageBac IDs of the parent/guardian records linked to this student.","items":{"type":"integer"}}}}]},"PersonalInformation":{"type":"object","description":"Common personal and contact fields shared by Teacher, Student, and Parent schemas. On POST (create), email and last_name are required. On PATCH (update), only include fields you want to change.\n","properties":{"email":{"type":"string","description":"User’s primary email address. Used for login and notifications. Required on create."},"first_name":{"type":"string","description":"User’s first given name."},"middle_name":{"type":"string","description":"User’s additional name."},"password":{"type":"string","description":"Minimum 6-character password. Only used on POST (create) and PATCH (update). Never returned in GET responses. If omitted on create, a random password is generated and the user receives a welcome email.\n"},"last_name":{"type":"string","description":"User’s surname."},"nickname":{"type":"string","description":"User’s handle (may differ to given name)."},"other_name":{"type":"string","description":"User’s additional names or variant in a different language."},"identifier":{"type":"string","description":"School’s own unique ID for user."},"gender":{"type":"string","description":"The user's gender. Accepts \"Male\", \"Female\", or other values depending on school configuration."},"birthday":{"type":"string","description":"User’s dob; yyyy-mm-dd."},"phone_number":{"type":"string","description":"User’s home number."},"mobile_phone_number":{"type":"string","description":"User’s mobile number."},"street_address":{"type":"string","description":"First line of user’s home address."},"street_address_ii":{"type":"string","description":"Second (optional) line of user’s home address."},"city":{"type":"string","description":"City of user’s home address."},"state":{"type":"string","description":"State of user’s home address."},"zipcode":{"type":"string","description":"Postal/zip code of user’s home address."},"country":{"type":"string","description":"Country of user’s home address."},"nationalities":{"type":"array","description":"One or more nationalities of the user.","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"},"description":"Fluent language/s of the user."},"account_uid":{"type":"string","readOnly":true,"description":"A user's Portal Account UID"},"timezone":{"type":"string","description":"The time zone of the user."}}},"Meta":{"type":"object","description":"Pagination metadata included in all list (index) responses.","properties":{"current_page":{"type":"integer","description":"The page number of the current result set, starting from 1."},"total_pages":{"type":"integer","description":"The total number of pages available for this query."},"total_count":{"type":"integer","description":"The total number of records matching the query across all pages."},"per_page":{"type":"integer","description":"The number of records returned per page. Defaults to 100; can be overridden with the per_page query parameter (max 200)."}}},"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}}}},"paths":{"/v2p0/students":{"get":{"summary":"Get all Students","operationId":"listStudents","tags":["Students"],"description":"Retrieves a paginated list of all students in the school. Returns personal details, program information,\nand any school-defined custom field values for each student. Results can be filtered by archive status,\nenrollment status, year group, homeroom advisor, modification date, deletion date, or a search query.\n","parameters":[{"$ref":"#/components/parameters/idsQueryParam"},{"name":"archived","in":"query","description":"Return only archived (1) or only active (0) students. If value is not specified, all students are returned.","required":false,"schema":{"type":"boolean"}},{"name":"status","in":"query","description":"Return students by status. Available statuses: <code>enrolled</code>, <code>withdrawn</code>, <code>graduated</code>. If value is not specified, all students are returned.","required":false,"schema":{"type":"string"}},{"name":"modified_since","in":"query","description":"An ISO 8601 timestamp to filter results to only those modified on or after the given date. Useful for syncing changes since a previous request.","required":false,"schema":{"type":"string"}},{"name":"year_group_ids","in":"query","description":"An integer list of year group ids to filter by. Accepts comma-separated values.","required":false,"schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":false},{"name":"year_group_ids[]","in":"query","description":"An integer list of year group ids to filter by. Accepts repeated query parameters.","required":false,"schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true},{"name":"homeroom_advisor_ids","in":"query","description":"An integer list of homeroom advisor (teacher) ids to filter by. Accepts comma-separated values.","required":false,"schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":false},{"name":"homeroom_advisor_ids[]","in":"query","description":"An integer list of homeroom advisor (teacher) ids to filter by. Accepts repeated query parameters.","required":false,"schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true},{"name":"page","in":"query","description":"The page number to return. Defaults to 1.","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","description":"The number of records per page. Defaults to 100.","required":false,"schema":{"type":"string"}},{"name":"deleted_since","in":"query","description":"An ISO 8601 timestamp to filter results to only those soft-deleted on or after the given date. Returns deleted student records for sync purposes.","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","description":"A string to search across the following fields: <code>first_name</code>, <code>last_name</code>, <code>middle_name</code>, <code>nickname</code>, <code>other_name</code>, <code>email</code>, <code>student_id</code>.","required":false,"schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"style":"form","explode":true,"description":"List of student ids. Accepts repeated params or a comma-separated string.","schema":{"type":"array","items":{"type":"integer"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"students":{"type":"array","items":{"$ref":"#/components/schemas/Student"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}}}}}}}
```

## Create New Student

> Creates a new student record. The \<code>Content-Type\</code> header must be set to \<code>application/json\</code>,\
> and the request body should contain the field structure as a JSON payload. Only users with \<code>admin\</code>\
> \<code>role\</code> are able to create new student records. The \<code>email\</code> field is required.\
> If a \<code>year\_group\_id\</code> is provided, the student is automatically assigned to the corresponding\
> year group and its default core grade. An optional \<code>password\</code> can be set but is never returned\
> in the response.\
> \
> Pass \<code>options\[send\_welcome\_email]: true\</code> to enqueue a welcome email (with password-set link) to the new student. Defaults to \<code>false\</code>.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"Student":{"anyOf":[{"$ref":"#/components/schemas/PersonalInformation"},{"type":"object","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this student in ManageBac. Read-only."},"sb_id":{"type":"string","description":"External identifier from SchoolsBuddy, if the school uses that integration. May be null."},"oa_id":{"type":"string","description":"External identifier from OpenApply, if the school uses that integration. May be null."},"graduated_on":{"type":"string","description":"Date when the student graduated, in yyyy-mm-dd format. Only present for students with a \"graduated\" status. Null for active or withdrawn students.\n"},"withdrawn_on":{"type":"string","description":"Date when the student was withdrawn from the school, in yyyy-mm-dd format. Only present for students with a \"withdrawn\" status. Null for active or graduated students.\n"},"student_id":{"type":"string","description":"The school’s own unique identifier for this student (e.g. a student number). Set by the school, not by ManageBac."},"homeroom_advisor_id":{"type":"integer","description":"ManageBac ID of the teacher assigned as this student’s homeroom advisor (tutor). Null if not assigned."},"year_group_id":{"type":"integer","description":"ManageBac ID of the year group this student is currently enrolled in."},"graduating_year":{"type":"integer","description":"The calendar year in which the student is expected to graduate. This is a four-digit year, not a date."},"parent_ids":{"type":"array","description":"ManageBac IDs of the parent/guardian records linked to this student.","items":{"type":"integer"}}}}]},"PersonalInformation":{"type":"object","description":"Common personal and contact fields shared by Teacher, Student, and Parent schemas. On POST (create), email and last_name are required. On PATCH (update), only include fields you want to change.\n","properties":{"email":{"type":"string","description":"User’s primary email address. Used for login and notifications. Required on create."},"first_name":{"type":"string","description":"User’s first given name."},"middle_name":{"type":"string","description":"User’s additional name."},"password":{"type":"string","description":"Minimum 6-character password. Only used on POST (create) and PATCH (update). Never returned in GET responses. If omitted on create, a random password is generated and the user receives a welcome email.\n"},"last_name":{"type":"string","description":"User’s surname."},"nickname":{"type":"string","description":"User’s handle (may differ to given name)."},"other_name":{"type":"string","description":"User’s additional names or variant in a different language."},"identifier":{"type":"string","description":"School’s own unique ID for user."},"gender":{"type":"string","description":"The user's gender. Accepts \"Male\", \"Female\", or other values depending on school configuration."},"birthday":{"type":"string","description":"User’s dob; yyyy-mm-dd."},"phone_number":{"type":"string","description":"User’s home number."},"mobile_phone_number":{"type":"string","description":"User’s mobile number."},"street_address":{"type":"string","description":"First line of user’s home address."},"street_address_ii":{"type":"string","description":"Second (optional) line of user’s home address."},"city":{"type":"string","description":"City of user’s home address."},"state":{"type":"string","description":"State of user’s home address."},"zipcode":{"type":"string","description":"Postal/zip code of user’s home address."},"country":{"type":"string","description":"Country of user’s home address."},"nationalities":{"type":"array","description":"One or more nationalities of the user.","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"},"description":"Fluent language/s of the user."},"account_uid":{"type":"string","readOnly":true,"description":"A user's Portal Account UID"},"timezone":{"type":"string","description":"The time zone of the user."}}},"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}}}},"paths":{"/v2p0/students":{"post":{"summary":"Create New Student","operationId":"createStudent","tags":["Students"],"description":"Creates a new student record. The <code>Content-Type</code> header must be set to <code>application/json</code>,\nand the request body should contain the field structure as a JSON payload. Only users with <code>admin</code>\n<code>role</code> are able to create new student records. The <code>email</code> field is required.\nIf a <code>year_group_id</code> is provided, the student is automatically assigned to the corresponding\nyear group and its default core grade. An optional <code>password</code> can be set but is never returned\nin the response.\n\nPass <code>options[send_welcome_email]: true</code> to enqueue a welcome email (with password-set link) to the new student. Defaults to <code>false</code>.\n","parameters":[],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"student":{"$ref":"#/components/schemas/Student"},"options":{"type":"object","properties":{"welcome_email":{"type":"string","enum":["enqueued","not_enqueued"]}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"student":{"allOf":[{"$ref":"#/components/schemas/Student"},{"description":"Fields for create student."}]},"options":{"type":"object","description":"Request directives applied during the create operation.","properties":{"send_welcome_email":{"type":"boolean","default":false,"description":"If true, a welcome email is enqueued for the newly created student."}}}},"required":["student"]}}}}}}}}
```

## Get a Student

> Retrieves a single student record by ID. Returns personal details including parent IDs, contact information,\
> and program enrollment. Depending on the value of the \<code>status\</code> field, the response includes either\
> a \<code>withdrawn\_on\</code> or \<code>graduated\_on\</code> date field. Fields with \<code>null\</code> values\
> are omitted from the response, but empty arrays and hashes are preserved.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"Student":{"anyOf":[{"$ref":"#/components/schemas/PersonalInformation"},{"type":"object","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this student in ManageBac. Read-only."},"sb_id":{"type":"string","description":"External identifier from SchoolsBuddy, if the school uses that integration. May be null."},"oa_id":{"type":"string","description":"External identifier from OpenApply, if the school uses that integration. May be null."},"graduated_on":{"type":"string","description":"Date when the student graduated, in yyyy-mm-dd format. Only present for students with a \"graduated\" status. Null for active or withdrawn students.\n"},"withdrawn_on":{"type":"string","description":"Date when the student was withdrawn from the school, in yyyy-mm-dd format. Only present for students with a \"withdrawn\" status. Null for active or graduated students.\n"},"student_id":{"type":"string","description":"The school’s own unique identifier for this student (e.g. a student number). Set by the school, not by ManageBac."},"homeroom_advisor_id":{"type":"integer","description":"ManageBac ID of the teacher assigned as this student’s homeroom advisor (tutor). Null if not assigned."},"year_group_id":{"type":"integer","description":"ManageBac ID of the year group this student is currently enrolled in."},"graduating_year":{"type":"integer","description":"The calendar year in which the student is expected to graduate. This is a four-digit year, not a date."},"parent_ids":{"type":"array","description":"ManageBac IDs of the parent/guardian records linked to this student.","items":{"type":"integer"}}}}]},"PersonalInformation":{"type":"object","description":"Common personal and contact fields shared by Teacher, Student, and Parent schemas. On POST (create), email and last_name are required. On PATCH (update), only include fields you want to change.\n","properties":{"email":{"type":"string","description":"User’s primary email address. Used for login and notifications. Required on create."},"first_name":{"type":"string","description":"User’s first given name."},"middle_name":{"type":"string","description":"User’s additional name."},"password":{"type":"string","description":"Minimum 6-character password. Only used on POST (create) and PATCH (update). Never returned in GET responses. If omitted on create, a random password is generated and the user receives a welcome email.\n"},"last_name":{"type":"string","description":"User’s surname."},"nickname":{"type":"string","description":"User’s handle (may differ to given name)."},"other_name":{"type":"string","description":"User’s additional names or variant in a different language."},"identifier":{"type":"string","description":"School’s own unique ID for user."},"gender":{"type":"string","description":"The user's gender. Accepts \"Male\", \"Female\", or other values depending on school configuration."},"birthday":{"type":"string","description":"User’s dob; yyyy-mm-dd."},"phone_number":{"type":"string","description":"User’s home number."},"mobile_phone_number":{"type":"string","description":"User’s mobile number."},"street_address":{"type":"string","description":"First line of user’s home address."},"street_address_ii":{"type":"string","description":"Second (optional) line of user’s home address."},"city":{"type":"string","description":"City of user’s home address."},"state":{"type":"string","description":"State of user’s home address."},"zipcode":{"type":"string","description":"Postal/zip code of user’s home address."},"country":{"type":"string","description":"Country of user’s home address."},"nationalities":{"type":"array","description":"One or more nationalities of the user.","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"},"description":"Fluent language/s of the user."},"account_uid":{"type":"string","readOnly":true,"description":"A user's Portal Account UID"},"timezone":{"type":"string","description":"The time zone of the user."}}},"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}},"NotFound":{"type":"object","description":"Returned when the requested resource cannot be found by the given ID.","properties":{"error":{"type":"string","description":"A human-readable message indicating which resource could not be found, including the model name and the ID that was looked up."}}}}},"paths":{"/v2p0/students/{id}":{"get":{"summary":"Get a Student","operationId":"getStudentByID","tags":["Students"],"description":"Retrieves a single student record by ID. Returns personal details including parent IDs, contact information,\nand program enrollment. Depending on the value of the <code>status</code> field, the response includes either\na <code>withdrawn_on</code> or <code>graduated_on</code> date field. Fields with <code>null</code> values\nare omitted from the response, but empty arrays and hashes are preserved.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"student":{"$ref":"#/components/schemas/Student"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}}}}
```

## Update a Student

> Updates a student record as specified by student ID. The \<code>Content-Type\</code> header must be set to\
> \<code>application/json\</code>, and the request body should contain only the fields you want to update as\
> a JSON payload. Only users with \<code>admin\</code> \<code>role\</code> are able to update students. Fields\
> such as \<code>last\_access\_at\</code> and \<code>last\_accessed\_at\</code> are read-only and cannot be updated.\
> If a \<code>year\_group\_id\</code> is provided, the student is moved to the new year group (legacy PYP groups\
> are rejected with a 404).<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"Student":{"anyOf":[{"$ref":"#/components/schemas/PersonalInformation"},{"type":"object","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this student in ManageBac. Read-only."},"sb_id":{"type":"string","description":"External identifier from SchoolsBuddy, if the school uses that integration. May be null."},"oa_id":{"type":"string","description":"External identifier from OpenApply, if the school uses that integration. May be null."},"graduated_on":{"type":"string","description":"Date when the student graduated, in yyyy-mm-dd format. Only present for students with a \"graduated\" status. Null for active or withdrawn students.\n"},"withdrawn_on":{"type":"string","description":"Date when the student was withdrawn from the school, in yyyy-mm-dd format. Only present for students with a \"withdrawn\" status. Null for active or graduated students.\n"},"student_id":{"type":"string","description":"The school’s own unique identifier for this student (e.g. a student number). Set by the school, not by ManageBac."},"homeroom_advisor_id":{"type":"integer","description":"ManageBac ID of the teacher assigned as this student’s homeroom advisor (tutor). Null if not assigned."},"year_group_id":{"type":"integer","description":"ManageBac ID of the year group this student is currently enrolled in."},"graduating_year":{"type":"integer","description":"The calendar year in which the student is expected to graduate. This is a four-digit year, not a date."},"parent_ids":{"type":"array","description":"ManageBac IDs of the parent/guardian records linked to this student.","items":{"type":"integer"}}}}]},"PersonalInformation":{"type":"object","description":"Common personal and contact fields shared by Teacher, Student, and Parent schemas. On POST (create), email and last_name are required. On PATCH (update), only include fields you want to change.\n","properties":{"email":{"type":"string","description":"User’s primary email address. Used for login and notifications. Required on create."},"first_name":{"type":"string","description":"User’s first given name."},"middle_name":{"type":"string","description":"User’s additional name."},"password":{"type":"string","description":"Minimum 6-character password. Only used on POST (create) and PATCH (update). Never returned in GET responses. If omitted on create, a random password is generated and the user receives a welcome email.\n"},"last_name":{"type":"string","description":"User’s surname."},"nickname":{"type":"string","description":"User’s handle (may differ to given name)."},"other_name":{"type":"string","description":"User’s additional names or variant in a different language."},"identifier":{"type":"string","description":"School’s own unique ID for user."},"gender":{"type":"string","description":"The user's gender. Accepts \"Male\", \"Female\", or other values depending on school configuration."},"birthday":{"type":"string","description":"User’s dob; yyyy-mm-dd."},"phone_number":{"type":"string","description":"User’s home number."},"mobile_phone_number":{"type":"string","description":"User’s mobile number."},"street_address":{"type":"string","description":"First line of user’s home address."},"street_address_ii":{"type":"string","description":"Second (optional) line of user’s home address."},"city":{"type":"string","description":"City of user’s home address."},"state":{"type":"string","description":"State of user’s home address."},"zipcode":{"type":"string","description":"Postal/zip code of user’s home address."},"country":{"type":"string","description":"Country of user’s home address."},"nationalities":{"type":"array","description":"One or more nationalities of the user.","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"},"description":"Fluent language/s of the user."},"account_uid":{"type":"string","readOnly":true,"description":"A user's Portal Account UID"},"timezone":{"type":"string","description":"The time zone of the user."}}},"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}},"NotFound":{"type":"object","description":"Returned when the requested resource cannot be found by the given ID.","properties":{"error":{"type":"string","description":"A human-readable message indicating which resource could not be found, including the model name and the ID that was looked up."}}}}},"paths":{"/v2p0/students/{id}":{"patch":{"summary":"Update a Student","operationId":"updateStudent","tags":["Students"],"description":"Updates a student record as specified by student ID. The <code>Content-Type</code> header must be set to\n<code>application/json</code>, and the request body should contain only the fields you want to update as\na JSON payload. Only users with <code>admin</code> <code>role</code> are able to update students. Fields\nsuch as <code>last_access_at</code> and <code>last_accessed_at</code> are read-only and cannot be updated.\nIf a <code>year_group_id</code> is provided, the student is moved to the new year group (legacy PYP groups\nare rejected with a 404).\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"student":{"$ref":"#/components/schemas/Student"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"student":{"allOf":[{"$ref":"#/components/schemas/Student"},{"description":"Fields for updating a student. Only include fields you want to change."}]}}}}}}}}}}
```

## Archive a Student

> Archives a student record as specified by student ID. This effectively removes the student from classes,\
> groups, and year groups. Either a \<code>withdrawn\_on\</code> or \<code>graduated\_on\</code> date must be\
> supplied to provide a reason for the archiving. You cannot supply both dates at the same time.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}}},"paths":{"/v2p0/students/{id}/archive":{"put":{"summary":"Archive a Student","operationId":"archiveStudent","tags":["Students"],"description":"Archives a student record as specified by student ID. This effectively removes the student from classes,\ngroups, and year groups. Either a <code>withdrawn_on</code> or <code>graduated_on</code> date must be\nsupplied to provide a reason for the archiving. You cannot supply both dates at the same time.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{}}},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","anyOf":[{"properties":{"withdrawn_on":{"type":"string","description":"Withdrawal date in yyyy-mm-dd format"}}},{"properties":{"graduated_on":{"type":"string","description":"Graduation date in yyyy-mm-dd format"}}}]}}},"description":"Either a withdrawal date or graduation date must be provided as the reason for archiving."}}}}}
```

## Unarchive a Student

> Reverses the archive operation on a student record as specified by ID. This restores the student so they\
> can be re-enrolled in classes, groups, and year groups. The \<code>graduated\_on\</code> and\
> \<code>withdrawn\_on\</code> dates are cleared.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}}},"paths":{"/v2p0/students/{id}/unarchive":{"put":{"summary":"Unarchive a Student","operationId":"unarchiveStudent","tags":["Students"],"description":"Reverses the archive operation on a student record as specified by ID. This restores the student so they\ncan be re-enrolled in classes, groups, and year groups. The <code>graduated_on</code> and\n<code>withdrawn_on</code> dates are cleared.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{}}},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"}}}}}}
```

## Send Welcome Email to a Student

> This endpoint enqueues a welcome email (with password-set link) for an existing student.\
> No request body is required. There is no restriction based on whether the student has\
> previously logged in. The endpoint is not idempotent — calling it twice enqueues two emails.<br>

```json
{"openapi":"3.0.3","info":{"title":"API V2P0","version":"v2p0"},"tags":[{"name":"Students","description":"Students are child users who use ManageBac to learn"}],"servers":[{"url":"https://api.managebac.com","description":"CA ManageBac API server."},{"url":"https://api.managebac.cn","description":"CN ManageBac API server."},{"url":"https://api.us.managebac.com","description":"US1 ManageBac API server."},{"url":"https://api.managebac.us","description":"US2 ManageBac API server."},{"url":"https://api.managebactest.com","description":"UAT ManageBac API server."},{"url":"https://{Host}","variables":{"Host":{"default":"api.devel.managebac.com","enum":["api.devel.managebac.com","api-faria.devel.managebac.com","api.managebac.dev"]}}}],"security":[{"bearerAuth":[]},{"authTokenQuery":[]},{"authTokenHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as `Bearer <token>`."},"authTokenQuery":{"type":"apiKey","name":"auth_token","in":"query","description":"Your V2 API authentication token may be passed in the parameters. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."},"authTokenHeader":{"type":"apiKey","name":"auth-token","in":"header","description":"Your V2 API authentication token may be passed in the header. To protect your key, use [environment variables](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key)."}},"schemas":{"AccessDeniedError":{"type":"object","description":"Returned when the API token is missing, invalid, or has been disabled.","properties":{"error":{"type":"string","description":"Always returns \"Access Denied\" when authentication fails. Check that your API token is valid and enabled."}}},"NotFound":{"type":"object","description":"Returned when the requested resource cannot be found by the given ID.","properties":{"error":{"type":"string","description":"A human-readable message indicating which resource could not be found, including the model name and the ID that was looked up."}}}}},"paths":{"/v2p0/students/{id}/welcome_email":{"post":{"summary":"Send Welcome Email to a Student","operationId":"sendStudentWelcomeEmail","tags":["Students"],"description":"This endpoint enqueues a welcome email (with password-set link) for an existing student.\nNo request body is required. There is no restriction based on whether the student has\npreviously logged in. The endpoint is not idempotent — calling it twice enqueues two emails.\n","parameters":[{"name":"id","in":"path","description":"Unique identifier for a student.","schema":{"type":"integer"},"required":true}],"responses":{"204":{"description":"No Content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDeniedError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}}}}}}}
```