> 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/openapply/public-rest-apis/v3/students.md).
# Students
This page describes all the APIs relating to students.
## Get All Students
> Retrieves a list of all students. Results are paginated.\
> Use the \`page\` and \`per\_page\` query parameters to control pagination.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]},"Parent":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquey identifies the parent record"},"first_name":{"type":"string"},"last_name":{"type":"string"},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"email":{"type":"string"},"student_id":{"type":"string"},"address":{"type":"string"},"address_ii":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"enrollment_year":{"type":"integer","nullable":true},"birth_date":{"type":"string","format":"date","nullable":true},"passport_id":{"type":"string","nullable":true},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"serial_number":{"type":"integer"},"custom_id":{"type":"string"},"name":{"type":"string"},"parent_id":{"type":"string","description":"Human-readable unique identifier commonly used for record reconsolidation across platforms. Populated and maintained by school"},"prefix":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobile_phone":{"type":"string","nullable":true},"parent_role":{"type":"string"},"full_address":{"type":"string","nullable":true},"managebac_parent_id":{"type":"string","nullable":true},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"profile_photo":{"type":"string","nullable":true},"profile_photo_updated_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"child_ids":{"type":"array","items":{"type":"integer"},"description":"Array of student ID of children associated with this parent."},"custom_fields":{"$ref":"#/components/schemas/CustomFields"}}}}},"paths":{"/api/v3/students":{"get":{"summary":"Get All Students","tags":["Students"],"operationId":"listStudents","description":"Retrieves a list of all students. Results are paginated.\nUse the `page` and `per_page` query parameters to control pagination.\n","parameters":[{"name":"page","in":"query","required":false,"description":"The page number of results to return.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Request for how many records to return.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"count","in":"query","required":false,"description":"Synonym for per_page","schema":{"type":"integer"}},{"name":"since_id","in":"query","required":false,"description":"Return results with an ID greater than the specified ID.","schema":{"type":"integer"}},{"name":"since_date","in":"query","required":false,"description":"Return results updated since the specified date, in UTC timezone","schema":{"type":"string","format":"date_time"}},{"name":"status","in":"query","required":false,"description":"Indicates the current state in a student's life-cycle","schema":{"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"]}},{"name":"status_level","in":"query","required":false,"description":"Filter students by status level, need to provide status slug","schema":{"type":"string"}},{"name":"enrollment_year","in":"query","required":false,"description":"Filter students by enrollment year","schema":{"type":"string"}},{"name":"parent_ids","in":"query","required":false,"description":"Filter students by parent IDs","schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"description":"Filter students by archived status. True returns only archived students, false returns only non-archived students. Omitting this parameter returns both.","schema":{"type":"boolean"}},{"name":"application_form_id","in":"query","required":false,"description":"Filter students by the Application form(s) they are currently attached to. Accepts a single form id or a comma-separated list (OR-combined); when the parameter is sent, any blank, non-numeric or empty-slot value is rejected with a 400 rather than ignored. For schools with one Application form per academic year this reproduces the admin Import/Export population; discover form ids via `GET /api/v3/forms` (`applicable_academic_years` maps years to form ids only for per-year form versions; for standalone multi-year forms use `GET /api/v3/students/applied`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"},{"name":"link_fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"students":{"type":"array","items":{"$ref":"#/components/schemas/Student"}},"linked":{"type":"object","properties":{"parents":{"type":"array","items":{"$ref":"#/components/schemas/Parent"}}}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pages":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}},"400":{"description":"blank or malformed application_form_id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```
## Create a student
> Create a student. Returns the unique \`id\` in the body as well as attributes if successful.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]},"StudentCreate":{"type":"object","properties":{"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade label (e.g. 'Grade 9', 'K'). Must match a valid grade configured for the school.","nullable":true,"readOnly":false},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true}},"required":["first_name","last_name"]}}},"paths":{"/api/v3/students":{"post":{"summary":"Create a student","tags":["Students"],"operationId":"CreateOneStudent","description":"Create a student. Returns the unique `id` in the body as well as attributes if successful.\n","parameters":[],"responses":{"201":{"description":"successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"422":{"description":"unprocessable entity"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentCreate"}}},"required":true}}}}}
```
## Get Students Who Applied for an Academic Year
> Lists students who applied for the given academic year, keyed on their Applied\
> status events rather than the live \`enrollment\_year\` tag or the current\
> application-form attachment. This is stable across form setups and re-applies,\
> so per-year application counts reconcile with the Conversion Funnel's\
> application stage. Use \`match=first\` to keep only students whose first-ever\
> application was for that year. The response shape matches \`GET /api/v3/students\`,\
> and each student carries their year-by-year \`application\_history\`.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]},"Parent":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquey identifies the parent record"},"first_name":{"type":"string"},"last_name":{"type":"string"},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"email":{"type":"string"},"student_id":{"type":"string"},"address":{"type":"string"},"address_ii":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"enrollment_year":{"type":"integer","nullable":true},"birth_date":{"type":"string","format":"date","nullable":true},"passport_id":{"type":"string","nullable":true},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"serial_number":{"type":"integer"},"custom_id":{"type":"string"},"name":{"type":"string"},"parent_id":{"type":"string","description":"Human-readable unique identifier commonly used for record reconsolidation across platforms. Populated and maintained by school"},"prefix":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"mobile_phone":{"type":"string","nullable":true},"parent_role":{"type":"string"},"full_address":{"type":"string","nullable":true},"managebac_parent_id":{"type":"string","nullable":true},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"profile_photo":{"type":"string","nullable":true},"profile_photo_updated_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"child_ids":{"type":"array","items":{"type":"integer"},"description":"Array of student ID of children associated with this parent."},"custom_fields":{"$ref":"#/components/schemas/CustomFields"}}}}},"paths":{"/api/v3/students/applied":{"get":{"summary":"Get Students Who Applied for an Academic Year","tags":["Students"],"operationId":"listStudentsAppliedByYear","description":"Lists students who applied for the given academic year, keyed on their Applied\nstatus events rather than the live `enrollment_year` tag or the current\napplication-form attachment. This is stable across form setups and re-applies,\nso per-year application counts reconcile with the Conversion Funnel's\napplication stage. Use `match=first` to keep only students whose first-ever\napplication was for that year. The response shape matches `GET /api/v3/students`,\nand each student carries their year-by-year `application_history`.\n","parameters":[{"name":"academic_year","in":"query","required":true,"description":"The academic year the student applied for (4-digit start year).","schema":{"type":"string"}},{"name":"match","in":"query","required":false,"description":"`any` (default) matches students with an Applied event for the year; `first` narrows to students whose earliest application was for that year.","schema":{"type":"string","enum":["any","first"],"default":"any"}},{"name":"page","in":"query","required":false,"description":"The page number of results to return.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Request for how many records to return.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"count","in":"query","required":false,"description":"Synonym for per_page","schema":{"type":"integer"}},{"name":"fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"},{"name":"link_fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"students":{"type":"array","items":{"$ref":"#/components/schemas/Student"}},"linked":{"type":"object","properties":{"parents":{"type":"array","items":{"$ref":"#/components/schemas/Parent"}}}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pages":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}},"400":{"description":"missing or malformed academic_year","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```
## Get a Student
> Fetch an instance of a student
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]}}},"paths":{"/api/v3/students/{id}":{"get":{"summary":"Get a Student","tags":["Students"],"operationId":"getOneStudent","description":"Fetch an instance of a student\n","parameters":[{"name":"id","in":"path","required":true,"description":"Serial database ID used to refer to a unique student record in OpenApply","schema":{"type":"integer"}},{"name":"fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"404":{"description":"student not found"}}}}}}
```
## Update a student
> Updates a student
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]},"StudentUpdate":{"type":"object","properties":{"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade label (e.g. 'Grade 9', 'K'). Must match a valid grade configured for the school.","nullable":true,"readOnly":false},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"effective_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date when the status change became effective (YYYY-MM-DD format only). Only used when status is being changed. If omitted, defaults to the later of today's date or the latest status history's effective date, in the school's configured timezone.","nullable":true,"readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true}}}}},"paths":{"/api/v3/students/{id}":{"patch":{"summary":"Update a student","tags":["Students"],"operationId":"UpdateOneStudent","description":"Updates a student\n","parameters":[{"name":"id","in":"path","required":true,"description":"Serial database ID used to refer to a unique student record in OpenApply","schema":{"type":"integer"}},{"name":"fields","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of fields to include in the response. Supports nested fields using parentheses\n"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"404":{"description":"student not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"unprocessable entity"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentUpdate"}}}}}}}}
```
## Update Student Status
> Update a student's status and/or status level
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Student":{"type":"object","properties":{"id":{"type":"integer","description":"Serial database ID that uniquely identifies the student record"},"first_name":{"type":"string","readOnly":false},"last_name":{"type":"string","readOnly":false},"email":{"type":"string","readOnly":false},"student_id":{"type":"string","description":"Human-readable identifier commonly used for record reconciliation across platforms. Populated and maintained by the school.","nullable":true,"readOnly":false},"address":{"type":"string","nullable":true,"readOnly":false},"address_ii":{"type":"string","nullable":true,"readOnly":false},"city":{"type":"string","nullable":true,"readOnly":false},"state":{"type":"string","nullable":true,"readOnly":false},"postal_code":{"type":"string","nullable":true,"readOnly":false},"enrollment_year":{"type":"integer","nullable":true,"readOnly":false},"birth_date":{"type":"string","format":"date","nullable":true,"readOnly":false},"grade":{"type":"string","description":"The grade"},"status":{"nullable":true,"type":"string","enum":["pending","applied","wait-listed","admitted","declined","enrolled","graduated","withdrawn"],"description":"The state of the application","readOnly":false},"country":{"type":"string","description":"The ISO 3166 country name","nullable":true},"other_name":{"type":"string","nullable":true},"preferred_name":{"type":"string","nullable":true},"name":{"type":"string"},"gender":{"type":"string","enum":["Male","Female","Non - Binary"],"nullable":true},"custom_status_name":{"type":"string","nullable":true,"description":"The school-specific display name for the current status","readOnly":true},"status_level":{"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student.","nullable":true},"status_changed_at":{"type":"string","format":"date-time","nullable":true},"status_level_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current `status_level` was last assigned or changed. `null` when the student has no status level."},"updated_at":{"type":"string","format":"date-time","nullable":true},"latest_activity_date":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"serial_number":{"type":"integer","nullable":true},"agent_id":{"type":"integer","nullable":true,"description":"The ID of the agent this student is associated to"},"managebac_student_id":{"type":"integer","nullable":true,"description":"Synonym for mb_id"},"mb_id":{"type":"string","nullable":true,"description":"Internal reference ID maintained by Faria SyncHub for integration with ManageBac"},"campus_id":{"type":"integer","nullable":true},"campus":{"type":"string","nullable":true,"description":"The name of the campus this student is associated to"},"custom_id":{"type":"string","nullable":true,"description":"Synonym for `student_id`"},"applicant_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"applied_at":{"type":"string","format":"date-time","nullable":true},"enrolled_at":{"type":"string","format":"date-time","nullable":true},"inquired_date":{"type":"string","format":"date-time","nullable":true},"inquired_at":{"type":"string","format":"date-time","nullable":true},"applied_date":{"type":"string","format":"date-time","nullable":true},"admitted_date":{"type":"string","format":"date-time","nullable":true},"wait_listed_date":{"type":"string","format":"date-time","nullable":true},"declined_date":{"type":"string","format":"date-time","nullable":true},"enrolled_date":{"type":"string","format":"date-time","nullable":true},"withdrawn_date":{"type":"string","format":"date-time","nullable":true},"graduated_date":{"type":"string","format":"date-time","nullable":true},"representative":{"type":"string","nullable":true},"enrollment_date":{"type":"string","format":"date"},"source_campaign":{"type":"string","nullable":true},"contact_date":{"type":"string","format":"date","nullable":true},"checklist_state":{"type":"string"},"passport_id":{"type":"string","nullable":true},"enrollment_grade":{"type":"string","nullable":true},"parent_ids":{"type":"array","items":{"type":"integer"},"description":"Array of parent ID of parents associated with this student."},"sibling_ids":{"type":"array","items":{"type":"integer"}},"student_flags":{"type":"array","items":{"type":"string"}},"sis_ids":{"type":"array","description":"External SIS integration identifiers. Only populated for integrations enabled on the school (iSAMS, PowerSchool, Engaged).","items":{"type":"object","properties":{"name":{"type":"string","description":"SIS integration name (e.g. iSAMS, PowerSchool, Engaged)"},"value":{"type":"string","description":"The external SIS identifier for this student"}}}},"application_form":{"type":"object","description":"The student's current Application form attachment. The pointer moves when a student re-applies; earlier application years remain available in `application_history`.","properties":{"id":{"type":"integer","nullable":true,"description":"The Application form the student is attached to; `null` when unattached. Discover form ids via `GET /api/v3/forms` (its `applicable_academic_years` maps years to form ids only for schools with per-year form versions; standalone forms report `[]` there)."},"academic_year":{"type":"integer","nullable":true,"description":"The academic year THIS student applied for (from their Applied status event), not the form's own year list. Falls back to the student's `enrollment_year` when they never reached the Applied status."}}},"application_history":{"type":"array","description":"One entry per academic year the student reached the Applied status: the earliest applied date per year, ordered by year. Survives re-applies, so `min(academic_year)` is the year the student first applied. Empty when the student never applied. Form ids are intentionally absent: earlier-year form submissions are destroyed when a student re-applies. Not the same structure as `application_history` in the `GET /api/v3/students/{id}/status_history` response, which lists individual status-change events.","items":{"type":"object","properties":{"academic_year":{"type":"integer"},"applied_date":{"type":"string","format":"date"}}}},"reenrollments":{"type":"array","items":{"$ref":"#/components/schemas/Reenrollment"}},"custom_fields":{"$ref":"#/components/schemas/CustomFields"},"archived":{"type":"boolean","description":"Whether the student is archived (typically Graduated or Withdrawn)","readOnly":false},"archived_on":{"type":"string","format":"date","nullable":true,"description":"The date when the student was archived","readOnly":false},"has_invalid_status_history":{"type":"boolean","description":"Whether the student's application status history is internally inconsistent","readOnly":true}}},"Reenrollment":{"type":"object","properties":{"ree_year":{"type":"string"},"ree_grade":{"type":"string"},"ree_status":{"type":"string"},"ree_decision_date":{"type":"string","format":"date"},"ree_status_changed_at":{"type":"string","format":"date-time"}},"required":["ree_year","ree_grade","ree_status"]},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]}}},"paths":{"/api/v3/students/{id}/status":{"patch":{"summary":"Update Student Status","tags":["Students"],"operationId":"updateStudentStatus","description":"Update a student's status and/or status level","parameters":[{"name":"id","in":"path","required":true,"description":"Serial database ID used to refer to a unique student record in OpenApply","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"404":{"description":"student not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"student":{"type":"object","properties":{"status":{"type":"string","description":"The new status for the student"},"status_level":{"type":"string","description":"The new status level for the student (must be valid for the given status)"},"effective_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date when the status change became effective (YYYY-MM-DD format only). If omitted, defaults to the later of today's date or the latest status history's effective date, in the school's configured timezone.","nullable":true}}}}}}},"description":"Status update parameters"}}}}}
```
## Get Student Status History
> Get the application status history for a specific student
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"StudentStatusHistory":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"integer"},"serial_number":{"type":"string"},"custom_id":{"type":"string"},"applicant_id":{"type":"string"},"application_history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"custom_name":{"type":"string"},"code":{"type":"string"}}},"enrollment_year":{"type":"string"},"effective_on":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"status_level":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}}}}},"paths":{"/api/v3/students/{id}/status_history":{"get":{"summary":"Get Student Status History","tags":["Students"],"operationId":"getStudentStatusHistory","description":"Get the application status history for a specific student","parameters":[{"name":"id","in":"path","required":true,"description":"Serial database ID used to refer to a unique student record in OpenApply","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentStatusHistory"}}}},"404":{"description":"student not found"}}}}}}
```
## Get Student Status Events
> Returns a paginated list of student status change events.\
> \
> Filterable by status updated\_at (since\_date\_to\_status) and enrollment\_year.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"StatusEvent":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"integer"},"custom_id":{"type":"string"},"enrollment_year":{"type":"integer"}}},"to":{"type":"object","properties":{"status":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"display_name":{"type":"string"},"updated_at":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date"}}},"status_level":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"updated_at":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date"}}}}},"from":{"type":"object","nullable":true,"properties":{"status":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"display_name":{"type":"string"},"updated_at":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date"}}},"status_level":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"updated_at":{"type":"string","format":"date"},"created_at":{"type":"string","format":"date"}}}}}}}}},"paths":{"/api/v3/students/status_events":{"get":{"summary":"Get Student Status Events","tags":["Students"],"operationId":"getStudentStatusEvents","description":"Returns a paginated list of student status change events.\n\nFilterable by status updated_at (since_date_to_status) and enrollment_year.\n","parameters":[{"name":"since_date_to_status","in":"query","required":false,"description":"Filter on status.updated_at","schema":{"type":"string","format":"date"}},{"name":"enrollment_year","in":"query","required":false,"description":"Filter on enrollment_year","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"The page number of results to return.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Request for how many records to return.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"count","in":"query","required":false,"description":"Synonym for per_page","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"students":{"type":"array","items":{"$ref":"#/components/schemas/StatusEvent"}},"meta":{"type":"object","properties":{"pages":{"type":"integer"},"per_page":{"type":"integer"},"total_entries":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}}}}}}
```
## Update student custom fields
> Updates student custom fields by field ID.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v3/students/{id}/custom_fields":{"patch":{"summary":"Update student custom fields","tags":["Students"],"operationId":"updateStudentCustomFields","description":"Updates student custom fields by field ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Student ID"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"integer"},"custom_fields":{"type":"object","additionalProperties":true}},"required":["id","custom_fields"]}}}}}},"404":{"description":"student not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_fields":{"type":"object","additionalProperties":true}},"required":["custom_fields"]}}}}}}}}
```
## Delete grouped field record
> Delete a grouped custom-field record from a student.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Students","description":"This page describes all the APIs relating to students."}],"servers":[{"url":"https://api.openapply.com","description":"CAN region auth server"},{"url":"https://api.openapply.cn","description":"CN region auth server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v3/students/{id}/custom_fields/{field_id}/records/{record_id}":{"delete":{"summary":"Delete grouped field record","tags":["Students"],"operationId":"deleteStudentCustomFieldRecord","description":"Delete a grouped custom-field record from a student.","parameters":[{"name":"id","in":"path","schema":{"type":"integer"},"description":"Student ID","required":true},{"name":"field_id","in":"path","schema":{"type":"integer"},"description":"Group field ID","required":true},{"name":"record_id","in":"path","schema":{"type":"integer"},"description":"Grouped record ID","required":true}],"responses":{"200":{"description":"deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"minimum group size violation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```