Students
Students are child users who use ManageBac to learn
Updates or replaces a student's avatar image. Accepts either a remote URL or a direct file upload.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Success
Unauthorized
Not Found
Bad Request
PUT /v2/students/{id}/avatar HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"avatar": {
"remote_file_url": "text"
}
}{
"status": "ok"
}Deletes a student's avatar image. This action cannot be undone.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Success
Unauthorized
Not Found
DELETE /v2/students/{id}/avatar HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "ok"
}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.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Return only records with the given IDs.
Return only archived (1) or only active (0) students. If value is not specified, all students are returned.
Return students by status. Available statuses: enrolled, withdrawn, graduated. If value is not specified, all students are returned.
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.
An integer list of year group ids to filter by. Accepts comma-separated values.
An integer list of year group ids to filter by. Accepts repeated query parameters.
An integer list of homeroom advisor (teacher) ids to filter by. Accepts comma-separated values.
An integer list of homeroom advisor (teacher) ids to filter by. Accepts repeated query parameters.
The page number to return. Defaults to 1.
The number of records per page. Defaults to 100.
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.
A string to search across the following fields: first_name, last_name, middle_name, nickname, other_name, email, student_id.
List of student ids. Accepts repeated params or a comma-separated string.
student_ids=1,2,3 OR student_ids[]=1&student_ids[]=2Success
Unauthorized
GET /v2/students HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"students": [
{
"id": 2054,
"email": "331-cstewart@mita.name",
"first_name": "Kevin",
"last_name": "Williams",
"archived": false,
"ui_language": "en",
"created_at": "2021-06-28T12:40:05.000Z",
"updated_at": "2021-06-28T12:40:05.000Z",
"student_id": "AA1001",
"identifier": "AA1001",
"gender": "Male",
"timezone": "Europe/Kyiv",
"parent_ids": [],
"street_address": "81856 Upham Place",
"city": "San Diego",
"state": "56981",
"zipcode": "82211",
"country": "SI",
"nationalities": [],
"languages": [],
"role": "Student"
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1,
"per_page": 100
}
}Creates a new student record. The Content-Type header must be set to application/json, and the request body should contain the field structure as a JSON payload. Only users with admin role are able to create new student records. The email field is required. If a year_group_id is provided, the student is automatically assigned to the corresponding year group and its default core grade. An optional password can be set but is never returned in the response.
Pass options[send_welcome_email]: true to enqueue a welcome email (with password-set link) to the new student. Defaults to false.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Fields for create student.
Success
Unauthorized
Unprocessable Content
POST /v2/students HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 563
{
"student": {
"email": "richard.chandler@eduvo.com",
"first_name": "Richard",
"middle_name": "David",
"password": "qwerty9876",
"last_name": "Chandler",
"nickname": "Ricky",
"other_name": "",
"identifier": "AA1001",
"gender": "Male",
"birthday": "1972-10-24",
"phone_number": "977 840-2231",
"mobile_phone_number": "977 840-2231",
"street_address": "301 Massachusetts Ave",
"street_address_ii": "",
"city": "Lunenburg",
"state": "Virginia",
"zipcode": "1462",
"country": "United States",
"nationalities": [
"US",
"GB"
],
"languages": [
"ENG"
],
"timezone": "Europe/Kyiv"
},
"options": {
"send_welcome_email": false
}
}{
"student": {
"id": 2063,
"email": "kevin.epelbaum@eduvo.com",
"first_name": "Kevin",
"last_name": "Epelbaum",
"archived": false,
"ui_language": "en",
"created_at": "2021-06-28T12:40:10.000Z",
"updated_at": "2021-06-28T12:40:10.000Z",
"student_id": "AA1001",
"identifier": "AA1001",
"parent_ids": [],
"nationalities": [],
"languages": []
},
"options": {
"welcome_email": "enqueued"
}
}Retrieves a single student record by ID. Returns personal details including parent IDs, contact information, and program enrollment. Depending on the value of the status field, the response includes either a withdrawn_on or graduated_on date field. Fields with null values are omitted from the response, but empty arrays and hashes are preserved.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Success
Unauthorized
Not Found
GET /v2/students/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"student": {
"id": 2057,
"email": "mimimi@yahoo.com",
"first_name": "Jessica",
"last_name": "Ortiz",
"archived": false,
"ui_language": "en",
"created_at": "2021-06-28T12:40:06.000Z",
"updated_at": "2021-06-28T12:40:06.000Z",
"student_id": "AA1001",
"identifier": "AA1001",
"gender": "Male",
"timezone": "Australia/Adelaide",
"ee_advisor_id": 456,
"parent_ids": [],
"street_address": "709 Fieldstone Plaza",
"city": "Pinole",
"state": "54245",
"zipcode": "39977",
"country": "NI",
"nationalities": [],
"languages": [],
"role": "Student"
}
}Updates a student record as specified by student ID. The Content-Type header must be set to application/json, and the request body should contain only the fields you want to update as a JSON payload. Only users with admin role are able to update students. Fields such as last_access_at and last_accessed_at are read-only and cannot be updated. If a year_group_id is provided, the student is moved to the new year group (legacy PYP groups are rejected with a 404).
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Fields for updating a student. Only include fields you want to change.
Success
Unauthorized
Not Found
Unprocessable Content
PATCH /v2/students/{id} HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 524
{
"student": {
"email": "richard.chandler@eduvo.com",
"first_name": "Richard",
"middle_name": "David",
"password": "qwerty9876",
"last_name": "Chandler",
"nickname": "Ricky",
"other_name": "",
"identifier": "AA1001",
"gender": "Male",
"birthday": "1972-10-24",
"phone_number": "977 840-2231",
"mobile_phone_number": "977 840-2231",
"street_address": "301 Massachusetts Ave",
"street_address_ii": "",
"city": "Lunenburg",
"state": "Virginia",
"zipcode": "1462",
"country": "United States",
"nationalities": [
"US",
"GB"
],
"languages": [
"ENG"
],
"timezone": "Europe/Kyiv"
}
}{
"student": {
"id": 2070,
"email": "kevin.epelbaum@eduvo.com",
"first_name": "Kevin",
"last_name": "Epelbaum",
"archived": false,
"ui_language": "en",
"created_at": "2021-06-28T12:40:12.000Z",
"updated_at": "2021-06-28T12:40:12.000Z",
"student_id": "AA1002",
"identifier": "AA1002",
"gender": "Male",
"timezone": "Atlantic/Cape_Verde",
"parent_ids": [],
"street_address": "9 Aberg Drive",
"city": "Fowler",
"state": "70059-4573",
"zipcode": "93186",
"country": "PT",
"nationalities": [],
"languages": []
}
}Archives a student record as specified by student ID. This effectively removes the student from classes, groups, and year groups. Either a withdrawn_on or graduated_on date must be supplied to provide a reason for the archiving. You cannot supply both dates at the same time.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Success
Unauthorized
Not Found
PUT /v2/students/{id}/archive HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"withdrawn_on": "text"
}{
"status": "ok"
}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 graduated_on and withdrawn_on dates are cleared.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
Success
Unauthorized
Not Found
PUT /v2/students/{id}/unarchive HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "ok"
}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.
OAuth 2.0 Bearer token obtained via client credentials grant. Pass the token in the Authorization header as Bearer <token>.
Unique identifier for a student.
No Content
No content
Unauthorized
Not Found
POST /v2/students/{id}/welcome_email HTTP/1.1
Host: api.managebac.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Last updated