ManageBac

Notes

  • Null values are never rendered.
  • Null values are ignored in POST requests.
  • Empty string values are not ignored and will overwrite existing values.
  • Any call will return an error when it can’t find a user for mass assignment. E.g. parent_ids, child_ids.
  • Parameters available for index actions stack using AND logic. Using modified_since and deleted_since at the same time may not return an expected result because deletion doesn’t change the record modification timestamp.
  • Any users who have the admin role are read-only through the API for security reasons.
  • All timestamp fields are in ISO8601 format, i.e yyyy-mm-ddThh:mm:ss.sssTZ, for example 2017-11-06T04:35:00.000GST.

IB Groups

Get all IB Groups

GET /v2/ib-groups

Retrieves the basic information of a school’s IB Groups. Returns the group name, program, grade level and student IDs of the participants.

Headers

Header Description
auth-token Your V2 API authentication token

Optional parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/ib-groups \
  --header 'auth-token: {{token}}'

Sample response

{
  "ib_groups": [
    {
      "id": 1,
      "name": "IB Diploma Group of 2019 (Grade 12)",
      "program": "IB Diploma",
      "grade": "Grade 12",
      "student_ids": [
        6
      ]
    },
    {
      "id": 2,
      "name": "IB MYP Group of 2019 (Year 4)",
      "program": "IB Middle Years",
      "grade": "Year 4",
      "student_ids": [
        7
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2,
    "per_page": 100
  }
}

Get advisors

GET /v2/ib-groups/:id/advisors

Retrieves the Homeroom, CAS, EE and ToK advisors for a specified IB group. Returns their ID and roles.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies an IB group

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/ib-groups/:id/advisors \
  --header 'auth-token: {{token}}'

Sample response

{
  "advisors": [
    {
      "id": 1,
      "roles": [
        "homeroom"
      ]
    },
    {
      "id": 2,
      "roles": [
        "cas"
      ]
    }
  ]
}

Get students for an IB Group

GET /v2/ib-groups/:id/students

Retrieves all students belonging to the IB Group specified by id.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies an IB Group id.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/ib-groups/:id/students \
  --header 'auth-token: {{token}}'

Sample response

{
  "student_ids": [
    6
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 100
  }
}

Add Students to an IB Group

POST /v2/ib-groups/:id/add_students

Adds the list of student IDs to the specified IB Group.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
student_ids An array of Student IDs to add to the IB Group

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/ib-groups/:id/add_students \
  --header 'auth-token: {{token}}' \
  --data '{
    "student_ids": [
      11997355
    ]
  }'

Sample response

{
  "status": "ok"
}

Remove Students from an IB Group

POST /v2/ib-groups/:id/remove_students

Removes the list of student IDs from the specified IB Group.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
student_ids An array of Student IDs to remove from the IB Group

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/ib-groups/:id/remove_students \
  --header 'auth-token: {{token}}' \
  --data '{
    "student_ids": [
      11997355
    ]
  }'

Sample response

{
  "status": "ok"
}

Classes Groups

Get all Classes

GET /v2/classes

Retrieves all classes. Returns at least name, ID, grade and program as well as any other values you have defined.

Note: By default, if classes can’t be sorted by subject_group they are sorted alphabetically by name.

Headers

Header Description
auth-token Your V2 API authentication token

Optional parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.
archived A boolean that if set returns only archived classes.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes \
  --header 'auth-token: {{token}}'

Sample response

{
    "classes": [
        {
            "id": 10283776,
            "name": "IB DP Norwegian A Language and literature SL (Grade 12)",
            "uniq_id": "",
            "class_section": "",
            "start_term_id": 29227,
            "end_term_id": 29227,
            "created_at": "2016-06-02T05:21:54.000-04:00",
            "updated_at": "2017-06-14T11:39:14.000-04:00",
            "grade": "Grade 12",
            "applicable_levels": [
                "SL"
            ],
            "program": "IB Diploma",
            "subject_id": 139,
            "subject_name": "Norwegian",
            "subject_group": "Language and literature",
            "teachers": [
                {
                    "teacher_id": 10947500,
                    "show_on_reports": true
                }
            ]
        },
        {
            "id": 10283777,
            "name": "IB DP Norwegian A Literature and Performance SL (Grade 12)",
            "uniq_id": "",
            "class_section": "",
            "start_term_id": 29227,
            "end_term_id": 29227,
            "created_at": "2016-06-02T05:22:24.000-04:00",
            "updated_at": "2017-06-14T11:39:14.000-04:00",
            "grade": "Grade 12",
            "applicable_levels": [
                "SL"
            ],
            "program": "IB Diploma",
            "subject_id": 139,
            "subject_name": "Norwegian",
            "subject_group": "Language and literature",
            "teachers": [
                {
                    "teacher_id": 10947500,
                    "show_on_reports": true
                }
            ]
        },
        {
            "id": 10283778,
            "name": "IB DP Swedish A Literature SL (Grade 12)",
            "uniq_id": "",
            "class_section": "",
            "start_term_id": 29227,
            "end_term_id": 29227,
            "created_at": "2016-06-02T05:22:55.000-04:00",
            "updated_at": "2017-06-14T11:39:14.000-04:00",
            "grade": "Grade 12",
            "applicable_levels": [
                "SL"
            ],
            "program": "IB Diploma",
            "subject_id": 154,
            "subject_name": "Swedish",
            "subject_group": "Language and literature",
            "teachers": [
                {
                    "teacher_id": 10947500,
                    "show_on_reports": true
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "next_page": 1,
        "total_pages": 1,
        "total_count": 3,
        "per_page": 100
    }
}

Get single Class

GET /v2/classes/:id

Retrieves a single class specified by id. Returns an ID, details and the IDs of teachers.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies a class id.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes/:id \
  --header 'auth-token: {{token}}'

Sample response

{
  "class": {
    "id": 4,
    "name": "IB DP English A (Grade 11)",
    "grade": "Grade 11",
    "applicable_levels": [
      "HL",
      "SL"
    ],
    "program": "IB Diploma",
    "subject_name": "English",
    "subject_group": "Language and literature",
    "teachers": [
      {
        "teacher_id": 1,
        "show_on_reports": false
      },
      {
        "teacher_id": 3,
        "show_on_reports": false
      }
    ]
  }
}

Get students for a Class

GET /v2/classes/:id/students

Retrieves all students belonging to the class specified by id.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies a class id.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes/:id/students \
  --header 'auth-token: {{token}}'

Sample response

{
  "student_ids": [
    6
  ],
  "student_levels": {
    "6": "SL"
  },
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 100
  }
}

Add Students to a Class

POST /v2/classes/:id/add_students

Adds the list of student IDs to the specified class.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
student_ids An array of Student IDs to add to the class

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/classes/:id/add_students \
  --header 'auth-token: {{token}}' \
  --data '{
    "student_ids": [
      11997355
    ]
  }'

Sample response

{
  "status": "ok"
}

Remove Students from a Class

POST /v2/classes/:id/remove_students

Removes the list of student IDs from the specified class.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
student_ids An array of Student IDs to remove from the class

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/classes/:id/remove_students \
  --header 'auth-token: {{token}}' \
  --data '{
    "student_ids": [
      11997355
    ]
  }'

Sample response

{
  "status": "ok"
}

Get Tasks for a Class

GET /v2/classes/:id/tasks?term_id=:term_id

Retrieves all tasks belonging to the class specified by id. If you don’t specify a term_id then the class’ start_term and end_term values are used to filter the tasks returned.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies a class id.

Optional parameters

Parameter Description
term_id A numeric value that specifies a term id.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes/:id/tasks \
  --header 'auth-token: {{token}}'

Sample response

{
  "tasks": [
    {
      "id": 18376694,
      "name": "Modelling tooth decay",
      "notes": "",
      "draft": false,
      "task_type": "summative",
      "dropbox": false,
      "turnitin": false,
      "due_date": "2017-10-25T03:05:00+08:00",
      "unit": {
        "id": 8,
        "title": "In Depth Study of Hydrocarbons "
      },
      "category": {
        "id": 11390960,
        "name": "Test",
        "weight": 20
      },
      "assessment_types": {
        "comments": {},
        "points": {
          "max_score": 5
        }
      }
    }
  ]
}

Get Term Grades for a Class Assessment

GET /v2/classes/:class_id/assessments/term/:term_id/term-grades

Retrieves all term grades for the term specified by term_id belonging to the class specified by class_id.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
class_id A numeric value that specifies a class id.
term_id A numeric value that specifies a term.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes/:class_id/assessments/term/:term_id/term-grades \
  --header 'auth-token: {{token}}'

Sample response

{
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 2,
        "per_page": 100
    },
    "students": [
        {
            "id": 12068821,
            "name": "Gomez, Joyce",
            "term_grade": {
                "grade": null,
                "average": {
                    "percent": null,
                    "grade": null
                },
                "comments": null,
                "rubrics": [
                    {
                       "id": 11181,
                       "title": "Predicted Grade",
                       "grade": "A"
                    }
                ]
            }
        },
        {
            "id": 12068757,
            "name": "Evans, Raymond",
            "term_grade": {
                "grade": null,
                "average": {
                    "percent": 12.5,
                    "grade": "F"
                },
                "comments": null,
                "rubrics": [
                    {
                       "id": 11181,
                       "title": "Predicted Grade",
                       "grade": "C"
                    }
                ]
            }
        }
    ]
}

Get Gradebook Grades for a Class Assessment

GET /v2/classes/:class_id/assessments/term/:term_id/grades

Retrieves all gradebook grades for the term specified by term_id belonging to the class specified by class_id.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
class_id A numeric value that specifies a class id.
term_id A numeric value that specifies a term.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/classes/:id/assessments/term/:term_id/grades \
  --header 'auth-token: {{token}}'

Sample response

{
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 2,
        "per_page": 100
    },
    "students": [
        {
            "id": 12068821,
            "name": "Gomez, Joyce",
            "assignments": [
                {
                    "id": 18376636,
                    "name": "dff",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 32
                },
                {
                    "id": 18376694,
                    "name": "Modelling tooth decay",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 5
                },
                {
                    "id": 18376845,
                    "name": "Mixed level assignment",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 12
                },
                {
                    "id": 18376852,
                    "name": "Trigonometry Unit Test",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 112
                },
                {
                    "id": 18376858,
                    "name": "Trigonometry Unit Test1",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 21
                }
            ]
        },
        {
            "id": 12068757,
            "name": "Evans, Raymond",
            "assignments": [
                {
                    "id": 18376636,
                    "name": "dff",
                    "group_mark": "F",
                    "comment": "",
                    "score": 4,
                    "max_points": 32
                },
                {
                    "id": 18376694,
                    "name": "Modelling tooth decay",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 5
                },
                {
                    "id": 18376845,
                    "name": "Mixed level assignment",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 12
                },
                {
                    "id": 18376852,
                    "name": "Trigonometry Unit Test",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 112
                },
                {
                    "id": 18376858,
                    "name": "Trigonometry Unit Test1",
                    "group_mark": null,
                    "comment": null,
                    "score": null,
                    "max_points": 21
                }
            ]
        }
    ]
}

Parents group

Get all Parents

GET /v2/parents

Retrieves all parents. Returns an ID, personal details and the IDs of children.

Headers

Header Description
auth-token Your V2 API authentication token

Optional parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.
deleted_since A timestamp to filter the deletion date of results.
q A string to search across all fields for.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/parents \
  --header 'auth-token: {{token}}'

Sample response

{
  "parents": [
    {
      "id": 4,
      "email": "[email protected]",
      "first_name": "Adrienne",
      "last_name": "Epelbaum",
      "archived": false,
      "gender": "Male",
      "child_ids": [
        6,
        7,
        8
      ],
      "street_address": "893 Thompson Center",
      "city": "Fowler",
      "state": "80219-6176",
      "zipcode": "66658",
      "country": "JE",
      "nationalities": [
        "US",
        "GB"
      ],
      "languages": [
        "ENG"
      ]
    },
    {
      "id": 5,
      "email": "[email protected]",
      "first_name": "Thomas",
      "last_name": "Epelbaum",
      "archived": false,
      "gender": "Male",
      "child_ids": [
        6,
        7,
        8
      ],
      "street_address": "799 Maple Plaza",
      "city": "Bellflower",
      "state": "85881",
      "zipcode": "16567",
      "country": "JE",
      "nationalities": [
        "US",
        "ES"
      ],
      "languages": [
        "ENG"
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2,
    "per_page": 100
  }
}

Get single Parent

GET /v2/parents/:id

Retrieves a single parent specified by id. Returns an ID, personal details and the IDs of children.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
id A numeric value that specifies a parent id.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/parents/:id \
  --header 'auth-token: {{token}}'

Sample response

{
  "parent": {
    "id": 4,
    "email": "[email protected]",
    "first_name": "Adrienne",
    "last_name": "Epelbaum",
    "archived": false,
    "gender": "Male",
    "child_ids": [
      6,
      7,
      8
    ],
    "street_address": "6 Hazelcrest Avenue",
    "city": "Half Moon Bay",
    "state": "87141",
    "zipcode": "79016",
    "country": "PK",
    "nationalities": [
      "US",
      "GB"
    ],
    "languages": [
      "ENG"
    ]
  }
}

Create new Parent

POST /v2/parents

Creates a new parent record. You must set the Content-Type header to application/json and the request body should contain the field structure as a JSON payload.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/parents \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "parent": {
    "email": "[email protected]",
    "first_name": "Stepan",
    "middle_name": "",
    "last_name": "Bandera",
    "nickname": "",
    "other_name": "",
    "gender": "M",
    "birthday": "1909-01-01",
    "phone_number": "",
    "mobile_phone_number": "",
    "street_address": "",
    "street_address_ii": "",
    "city": "Old Uhryniv",
    "state": "",
    "zipcode": "",
    "country": "UA",
    "salutation": "",
    "title": "",
    "employer": "",
    "work_email": "",
    "work_phone": "",
    "work_address": "",
    "work_address_ii": "",
    "work_fax": "",
    "work_city": "",
    "work_state": "",
    "work_postal_code": "",
    "work_country": "",
    "password": "very strong pass phrase",
    "child_ids": [8],
    "nationalities": ["UA"],
    "languages": ["UKR"]
  }
}
'

Sample response

{
  "parent": {
    "id": 11,
    "email": "[email protected]",
    "first_name": "Stepan",
    "last_name": "Bandera",
    "archived": false,
    "gender": "Male",
    "birthday": "1909-01-01",
    "child_ids": [
      8
    ],
    "city": "Old Uhryniv",
    "country": "UA",
    "nationalities": [
      "UA"
    ],
    "languages": [
      "UKR"
    ]
  }
}

Update Parent

PATCH /v2/parents/:id

Updates the parent record with the specified ID. You must set the Content-Type header to application/json and the request body should contain the fields you want to update as a JSON payload.

Only teacher users with the admin role are able to update users.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request PATCH \
  --url https://api.managebac.com/v2/parents/:id \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "parent": {
    "zipcode": "76000",
    "country": "UA"
  }
}
'

Sample response

{
  "parent": {
    "id": 4,
    "email": "[email protected]",
    "first_name": "Adrienne",
    "last_name": "Epelbaum",
    "archived": false,
    "gender": "Female",
    "child_ids": [
      6,
      7,
      8
    ],
    "street_address": "5 Thierer Parkway",
    "city": "King City",
    "state": "98259",
    "zipcode": "76000",
    "country": "UA",
    "nationalities": [
      "US",
      "GB"
    ],
    "languages": [
      "ENG"
    ]
  }
}

Archive a Parent

PUT /v2/parents/:id/archive

Archives the parent record with the specified ID, hiding the parent from groups etc.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request PUT \
  --url https://api.managebac.com/v2/parents/:id/archive \
  --header 'auth-token: {{token}}' \

Sample response

{
  "status": "ok"
}

Unarchive a Parent

PUT /v2/parents/:id/unarchive

Reverses the archive operation on the parent record with the specified ID, showing the parent in previous groups etc.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request PUT \
  --url https://api.managebac.com/v2/parents/:id/unarchive \
  --header 'auth-token: {{token}}' \

Sample response

{
  "status": "ok"
}

School group

Get school details

GET /v2/school

Retrieves the details and programs for the school the account belongs to.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/school \
  --header 'auth-token: {{token}}'

Sample response

{
  "school": {
    "subdomain": "seed",
    "name": "Faria International School",
    "country": "US",
    "language": "en",
    "programs": [
      "IB Diploma",
      "IB Middle Years",
      "IB Primary Years",
      "High School",
      "Middle School",
      "Primary School"
    ]
  }
}

Get academic years

GET /v2/school/academic-years

Retrieves the academic year details defined for each program a school runs. It returns academic years for each program including the list of academic year terms.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/school/academic-years \
  --header 'auth-token: {{token}}'

Sample response

{
  "academic_years": {
    "diploma": {
      "academic_years": [
        {
          "id": 26278,
          "name": "August 2017 – July 2018",
          "starts_on": "2017-08-15",
          "ends_on": "2018-07-30",
          "updated_at": "2017-12-21T16:50:47.000+08:00",
          "academic_terms": [
            {
              "id": 62755,
              "name": "Term 1",
              "starts_on": "2017-08-15",
              "ends_on": "2017-12-31",
              "updated_at": "2017-12-21T16:50:47.000+08:00",
              "exam_grade": false
            },
            {
              "id": 62756,
              "name": "Term 2",
              "starts_on": "2018-01-03",
              "ends_on": "2018-07-30",
              "updated_at": "2017-08-14T17:37:35.000+08:00",
              "exam_grade": false
            }
          ]
        }
      ]
    },
    "myp": {
      "academic_years": [
         {
           "id": 24648,
           "name": "August 2016 – July 2017",
           "starts_on": "2016-08-19",
           "ends_on": "2017-07-01",
           "updated_at": "2016-09-09T05:09:12.000+08:00",
           "academic_terms": [
             {
               "id": 58813,
               "name": "Term One",
               "starts_on": "2016-08-19",
               "ends_on": "2017-01-29",
               "updated_at": "2016-09-09T05:09:12.000+08:00",
               "exam_grade": false
             },
             {
               "id": 58814,
               "name": "Term 2",
               "starts_on": "2017-02-01",
               "ends_on": "2017-07-01",
               "updated_at": "2016-09-09T05:09:12.000+08:00",
               "exam_grade": false
             }
           ]
         }
      ]
    },
    "pyp": {
      "academic_years": [
        {
          "id": 31796,
          "name": "August 2017 – June 2018",
          "starts_on": "2017-08-10",
          "ends_on": "2018-06-03",
          "updated_at": "2017-11-28T23:54:16.000+08:00",
          "academic_terms": [
            {
              "id": 76082,
              "name": "Term One",
              "starts_on": "2017-08-10",
              "ends_on": "2018-01-01",
              "updated_at": "2017-11-28T23:54:16.000+08:00",
              "exam_grade": false
            },
            {
              "id": 76083,
              "name": "Quarter 1",
              "starts_on": "2018-01-04",
              "ends_on": "2018-06-03",
              "updated_at": "2017-11-28T23:54:16.000+08:00",
              "exam_grade": false
            }
          ]
        }
      ]
    }
  }
}

Get school grades

GET /v2/school/grades

Retrieves the grade details defined for each program a school runs. It returns grades grouped by each program.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/school/grades \
  --header 'auth-token: {{token}}'

Sample response

{
  "school": {
    "programs": [
      {
        "name": "IB Diploma",
        "code": "diploma",
        "grades": [
          {
            "name": "Grade 9",
            "label": "Pre-DP Grade 10",
            "code": "diploma;10",
            "uid": 100120013,
            "grade_number": 10
          },
          {
            "name": "Grade 10",
            "label": "Pre-DP Grade 11",
            "code": "diploma;11",
            "uid": 100120014,
            "grade_number": 11
          }
        ]
      },
      {
        "name": "IB Middle Years",
        "code": "myp",
        "grades": [
          {
            "name": "Year 1",
            "label": "Grade 6",
            "code": "myp;7",
            "uid": 100110010,
            "grade_number": 7
          },
          {
            "name": "Year 2",
            "label": "Grade 7",
            "code": "myp;8",
            "uid": 100110011,
            "grade_number": 8
          }
        ]
      },
      {
        "name": "IB Primary Years",
        "code": "pyp",
        "grades": [
          {
            "name": "Pre-Nursery",
            "label": "Test",
            "code": "pyp;-2",
            "uid": 100100001,
            "grade_number": -2
          },
          {
            "name": "Nursery",
            "label": "Pre-K3",
            "code": "pyp;-1",
            "uid": 100100002,
            "grade_number": -1
          }
        ]
      }
    ]
  }
}

Get school subjects

GET /v2/school/subjects

Retrieves the subject details defined for each program a school runs. It returns subjects grouped by each program.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/school/subjects \
  --header 'auth-token: {{token}}'

Sample response

{
  "subjects": {
    "diploma": [
      {
        "id": 1,
        "name": "Mathematical Studies",
        "group": "Mathematics",
        "hl": true,
        "sl": true
      },
      {
        "id": 16,
        "name": "Chinese",
        "group": "Language acquisition",
        "hl": true,
        "sl": true,
        "self_taught": false,
        "levels": [
          "B",
          "ab initio"
        ]
      },
      {
        "id": 27,
        "name": "French",
        "group": "Language acquisition",
        "hl": true,
        "sl": true,
        "self_taught": false,
        "levels": [
          "B",
          "ab initio"
        ]
      }
    ],
    "myp": [
      {
        "id": 348,
        "name": "Physical and health education",
        "group": "Physical and health education"
      },
      {
        "id": 350,
        "name": "Arts",
        "group": "Arts"
      }
    ]
  }
}

Students group

Get all students

GET /v2/students

Retrieves all children. Returns an ID, personal details and the IDs of parents.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.
deleted_since A timestamp to filter the deletion date of results.
q A string to search across all fields for.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/students \
  --header 'auth-token: {{token}}'

Sample response

{
  "students": [
    {
      "id": 6,
      "email": "[email protected]",
      "first_name": "Chloe",
      "last_name": "Epelbaum",
      "archived": false,
      "gender": "Female",
      "homeroom_advisor_id": 1,
      "class_grade": "Grade 12",
      "program": "IB Diploma",
      "ib_group_id": 1,
      "parent_ids": [
        4,
        5
      ],
      "street_address": "13980 High Crossing Plaza",
      "city": "Lathrop",
      "state": "29482-5294",
      "zipcode": "82433",
      "country": "SD",
      "nationalities": [
        "US",
        "GB"
      ],
      "languages": [
        "ENG"
      ],
      "graduating_year": 2018
    },
    {
      "id": 8,
      "email": "[email protected]",
      "first_name": "Henry",
      "last_name": "Epelbaum",
      "archived": false,
      "gender": "Male",
      "homeroom_advisor_id": 3,
      "class_grade": "Year 5",
      "program": "IB Primary Years",
      "ib_group_id": 7,
      "parent_ids": [
        4,
        5
      ],
      "street_address": "85284 Reindahl Alley",
      "city": "Antioch",
      "state": "44865-5391",
      "zipcode": "17035-1383",
      "country": "SD",
      "nationalities": [
        "US",
        "GB"
      ],
      "languages": [
        "ENG"
      ],
      "graduating_year": 2019
    },
    {
      "id": 7,
      "email": "[email protected]",
      "first_name": "Rachel",
      "last_name": "Epelbaum",
      "archived": false,
      "gender": "Female",
      "homeroom_advisor_id": 2,
      "class_grade": "Year 4",
      "program": "IB Middle Years",
      "ib_group_id": 2,
      "parent_ids": [
        4,
        5
      ],
      "street_address": "143 Sunnyside Center",
      "city": "Palo Alto",
      "state": "24281",
      "zipcode": "60037",
      "country": "SD",
      "nationalities": [
        "US",
        "GB"
      ],
      "languages": [
        "ENG"
      ],
      "graduating_year": 2019
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "per_page": 100
  }
}

Get single student

GET /v2/students/:id

Retrieves a single child specified by id. Returns an ID, details and the IDs of parents. Depending on the value of the status field (withdrawn or graduated), the related date field will have a different name, for example:

Withdrawn status

"status": "withdrawn",
"withdrawn_on": "2017-11-01",

Graduated status

"status": "graduated",
"graduated_on": "2017-11-01",

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/students/:id \
  --header 'auth-token: {{token}}'

Sample response

{
  "student": {
    "id": 11337989,
    "email": "[email protected]",
    "first_name": "Robert",
    "last_name": "White",
    "archived": false,
    "gender": "Male",
    "birthday": "2000-06-17",
    "phone_number": "",
    "mobile_phone_number": "",
    "photo_url": "http://api.mb.dev/v2/avatars/11337989/v1",
    "student_id": "S73744",
    "homeroom_advisor_id": 102721983,
    "attendance_start_date": "2016-08-22",
    "class_grade": "Grade 11",
    "program": "IB Diploma",
    "ib_group_id": 10075615,
    "parent_ids": [
      11231698,
      11231657
    ],
    "street_address": "",
    "street_address_ii": "",
    "city": "",
    "state": "",
    "zipcode": "",
    "country": "",
    "nationalities": [],
    "languages": [],
    "graduating_year": 2019,
    "enrollment_start_date": "2017-10-12",
    "status": "withdrawn",
    "withdrawn_on": "2017-11-01",
  }
}

Create new student

POST /v2/students

Creates a new student record. You must set the Content-Type header to application/json and the request body should contain the field structure as a JSON payload.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/students \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "student": {
    "email": "[email protected]",
    "first_name": "Kevin",
    "middle_name": "",
    "last_name": "Epelbaum",
    "nickname": "",
    "other_name": "",
    "gender": "m",
    "birthday": "2012-03-28",
    "phone_number": "+1 555 678678548",
    "mobile_phone_number": "+1 555 678342548",
    "student_id": "kevin-231231",
    "homeroom_advisor_id": 1,
    "ib_group_id": 3,
    "street_address": "711 Mercer Street",
    "city": "Wausau",
    "state": "Wisconsin",
    "zipcode": "54401",
    "country": "US",
    "password": "secret password phrase",
    "parent_ids": [2],
    "nationalities": ["GB", "US"],
    "languages": ["ENG"]
  }
}'

Sample response

{
  "student": {
    "id": 9,
    "email": "[email protected]",
    "first_name": "Kevin",
    "last_name": "Epelbaum",
    "archived": false,
    "gender": "Male",
    "birthday": "2012-03-28",
    "phone_number": "+1 555 678678548",
    "mobile_phone_number": "+1 555 678342548",
    "student_id": "kevin-231231",
    "homeroom_advisor_id": 1,
    "class_grade": "Year 3",
    "program": "IB Primary Years",
    "ib_group_id": 3,
    "parent_ids": [
      4,
      5
    ],
    "street_address": "711 Mercer Street",
    "city": "Wausau",
    "state": "Wisconsin",
    "zipcode": "54401",
    "country": "US",
    "nationalities": [
      "GB",
      "US"
    ],
    "languages": [
      "ENG"
    ]
  }
}

Update student

PATCH /v2/students/:id

Updates the student record with the specified ID. You must set the Content-Type header to application/json and the request body should contain the fields you want to update as a JSON payload.

Only teacher users with the admin role are able to update users.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request PATCH \
  --url https://api.managebac.com/v2/students/:id \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "student": {
    "nickname": "CE",
    "nationalities": ["GB", "US", "DE"],
    "languages": ["ENG"]
  }
}'

Sample response

{
  "student": {
    "id": 6,
    "email": "[email protected]",
    "first_name": "Chloe",
    "last_name": "Epelbaum",
    "nickname": "CE",
    "archived": false,
    "gender": "Female",
    "homeroom_advisor_id": 1,
    "class_grade": "Grade 12",
    "program": "IB Diploma",
    "ib_group_id": 1,
    "parent_ids": [
      4,
      5
    ],
    "street_address": "13980 High Crossing Plaza",
    "city": "Lathrop",
    "state": "29482-5294",
    "zipcode": "82433",
    "country": "SD",
    "nationalities": [
      "GB",
      "US",
      "DE"
    ],
    "languages": [
      "ENG"
    ]
  }
}

Archive a Student

PUT /v2/students/:id/archive

Archives the student record with the specified ID, hiding the student from classes, groups etc.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

One of the below is required.

Parameter Description
withdrawn_on A date in yyyy-mm-dd format
graduated_on A date in yyyy-mm-dd format

Sample request

curl --request PUT \
  --url https://api.managebac.com/v2/students/:id/archive \
  --header 'auth-token: {{token}}' \
  --data '{
      "graduated_on": "2017-05-05"
    }'

Sample response

{
  "status": "ok"
}

Unarchive a Student

PUT /v2/students/:id/unarchive

Reverses the archive operation on the student record with the specified ID, showing the student in previous classes, groups etc.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request PUT \
  --url https://api.managebac.com/v2/students/:id/unarchive \
  --header 'auth-token: {{token}}' \

Sample response

{
  "status": "ok"
}

Teachers group

Get all teachers

GET v2/teachers

Retrieves all teachers. Returns an ID and personal details.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.
deleted_since A timestamp to filter the deletion date of results.
q A string to search across all fields for.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/teachers \
  --header 'auth-token: {{token}}'

Sample response

{
  "teachers": [
    {
      "id": 1,
      "email": "[email protected]",
      "first_name": "Richard",
      "last_name": "Chandler",
      "archived": false,
      "gender": "Male",
      "street_address": "99590 Johnson Park",
      "city": "Blue Lake",
      "state": "85124",
      "zipcode": "72146",
      "country": "PT",
      "programs": [],
      "nationalities": [],
      "languages": [],
      "role": "Admin"
    },
    {
      "id": 2,
      "email": "[email protected]",
      "first_name": "Risa",
      "last_name": "Aoki",
      "archived": false,
      "gender": "Male",
      "street_address": "9 Pankratz Street",
      "city": "Susanville",
      "state": "56900",
      "zipcode": "34780-7928",
      "country": "PT",
      "programs": [],
      "nationalities": [
        "US",
        "GB"
      ],
      "languages": [
        "ENG"
      ],
      "role": "Advisor"
    },
    {
      "id": 3,
      "email": "[email protected]",
      "first_name": "Sharon",
      "last_name": "Arese",
      "archived": false,
      "gender": "Male",
      "street_address": "761 Crescent Oaks Plaza",
      "city": "Albany",
      "state": "07722",
      "zipcode": "48785",
      "country": "PT",
      "programs": [],
      "nationalities": [
        "US",
        "UA"
      ],
      "languages": [
        "ENG",
        "UKR"
      ],
      "role": "Admin"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "per_page": 100
  }
}

Get single teacher

GET /v2/teachers/:id

Retrieves a single teacher specified by id. Returns an ID and contact details.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/teachers/:id \
  --header 'auth-token: {{token}}'

Sample response

{
  "teacher": {
    "id": 2,
    "email": "[email protected]",
    "first_name": "Risa",
    "last_name": "Aoki",
    "archived": false,
    "gender": "Male",
    "street_address": "434 Monica Court",
    "city": "Orland",
    "state": "03802-6387",
    "zipcode": "50099",
    "country": "PK",
    "programs": [],
    "nationalities": [
      "US",
      "GB"
    ],
    "languages": [
      "ENG"
    ],
    "role": "Advisor"
  }
}

Create new teacher

POST /v2/teachers

Creates a new teacher record. You must set the Content-Type header to application/json and the request body should contain the field structure as a JSON payload.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request POST \
  --url https://api.managebac.com/v2/teachers \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "teacher": {
    "first_name": "John",
    "last_name": "Epelbaum",
    "email": "[email protected]"
  }
}'

Sample response

{
  "teacher": {
    "id": 10,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Epelbaum",
    "archived": false,
    "programs": [],
    "nationalities": [],
    "languages": [],
    "role": "Admin"
  }
}

Update teacher

PATCH /v2/teachers/:id

Updates the teacher record with the specified ID. You must set the Content-Type header to application/json and the request body should contain the fields you want to update as a JSON payload.

Only teacher users with the admin role are able to update users.

Headers

Header Description
auth-token Your V2 API authentication token
Content-Type application/json

Sample request

curl --request PATCH \
  --url https://api.managebac.com/v2/teachers/:id \
  --header 'auth-token: {{token}}' \
  --header 'content-type: application/json' \
  --data '{
  "teacher": {
    "nationalities": ["US"]
  }
}'

Sample response

{
  "teacher": {
    "id": 3,
    "email": "[email protected]",
    "first_name": "Sharon",
    "last_name": "Arese",
    "archived": false,
    "gender": "Female",
    "street_address": "69902 Kipling Park",
    "city": "Bell Gardens",
    "state": "23507-8279",
    "zipcode": "94640-2514",
    "country": "SD",
    "programs": [],
    "nationalities": [
      "US",
      "UA"
    ],
    "languages": [
      "ENG",
      "UKR"
    ],
    "role": "Advisor"
  }
}

Memberships group

Get all memberships

GET v2/memberships

Retrieves all student memberships of a class. Returns a class ID, user ID, a user role in the class and other details.

Headers

Header Description
auth-token Your V2 API authentication token

Required parameters

Parameter Description
modified_since A timestamp to filter the modification date of results.
page An integer defining the page of results to display.
per_page An integer defining the number of records to display per page.
deleted_since A timestamp to filter the deletion date of results.
q A string to search across all fields for.

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/memberships \
  --header 'auth-token: {{token}}'

Sample response

{
  "memberships": [{
      "id": 10643560,
      "user_id": 10193657,
      "level": 0,
      "created_at": "2010-06-29T21:43:04.000+08:00",
      "updated_at": "2010-06-29T21:43:04.000+08:00",
      "class_id": 10022310,
      "user_email": "[email protected]",
      "uniq_class_id": "BioHLGr12",
      "uniq_student_id": "BioHLGr12",
      "role": "Student"
    },
    {
      "id": 10643564,
      "user_id": 10193658,
      "level": 1,
      "created_at": "2010-06-29T21:46:19.000+08:00",
      "updated_at": "2010-06-29T21:46:19.000+08:00",
      "class_id": 10022310,
      "user_email": "[email protected]",
      "uniq_class_id": "BioHLGr12",
      "uniq_student_id": "BioHLGr12",
      "role": "Student"
    },
    {
      "id": 10833694,
      "user_id": 10193613,
      "created_at": "2011-02-04T02:54:29.000+08:00",
      "updated_at": "2011-02-04T02:54:29.000+08:00",
      "class_id": 10022310,
      "user_email": "[email protected]",
      "uniq_class_id": "BioHLGr12",
      "role": "Account Admin"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "per_page": 100
  }
}

Utilities

Ping

GET /v2/ping

Tests your API key is valid.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/ping \
  --header 'auth-token: {{token}}'

Sample response

{
  "pong": "ok"
}

Get avatar

GET /v2/avatars/:user_id

Retrieves the avatars of the user with the specified ID.

Headers

Header Description
auth-token Your V2 API authentication token

Sample request

curl --request GET \
  --url https://api.managebac.com/v2/avatars/:user_id \
  --header 'auth-token: {{token}}'

Sample response

json