> 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/search.md).
# Search
This page describes all the APIs relating to querying by student or parent attributes
## Get Parents' Searchable Attributes
> Fetch attributes that can be used for requests to /parents/search.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Search","description":"This page describes all the APIs relating to querying by student or parent attributes"}],"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":{"ParentSlug":{"type":"array","items":{"type":"string"}},"FormSlug":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","nullable":true}}}}},"paths":{"/api/v3/parents/searchable_keys":{"get":{"summary":"Get Parents' Searchable Attributes","tags":["Search"],"operationId":"getParentSearchableKeys","description":"Fetch attributes that can be used for requests to /parents/search.\n","responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"parent_slug":{"$ref":"#/components/schemas/ParentSlug"},"form_slug":{"$ref":"#/components/schemas/FormSlug"}}}}}}}}}}}
```
## Search Parents
> Return parent records that contain matching attribute/value pairs
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Search","description":"This page describes all the APIs relating to querying by student or parent attributes"}],"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":{"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"}}},"CustomFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"}},"CustomFieldValue":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}]}}},"paths":{"/api/v3/parents/search":{"get":{"summary":"Search Parents","tags":["Search"],"operationId":"searchParents","description":"Return parent records that contain matching attribute/value pairs\n","parameters":[{"name":"parent","in":"query","schema":{"type":"object"},"required":false,"description":"Search criteria for parents"},{"name":"field","in":"query","schema":{"type":"object"},"required":false,"description":"Search criteria for custom fields"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"parents":{"type":"array","items":{"$ref":"#/components/schemas/Parent"}}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```
## Get Students' Searchable Attributes
> Fetch attributes that can be used for requests to /students/search.\
> \
> The response's root will include arrays mapped to keys in the pattern of "x\_slugs" (i.e. "form\_slug") where x is the scope of included elements.\
> \
> For example, on the student application form ("student\_slug"), or form "form\_slug", supplementary forms, etc. \
> \
> The elements of the array are strings (i.e. "first\_name") that refer to field name that can be targeted for search.
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Search","description":"This page describes all the APIs relating to querying by student or parent attributes"}],"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":{"TagSlug":{"type":"array","items":{"type":"string"}},"StudentSlug":{"type":"array","items":{"type":"string"}},"FormSlug":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","nullable":true}}}}},"paths":{"/api/v3/students/searchable_keys":{"get":{"summary":"Get Students' Searchable Attributes","tags":["Search"],"operationId":"getStudentSearchableKeys","description":"Fetch attributes that can be used for requests to /students/search.\n\nThe response's root will include arrays mapped to keys in the pattern of \"x_slugs\" (i.e. \"form_slug\") where x is the scope of included elements.\n\nFor example, on the student application form (\"student_slug\"), or form \"form_slug\", supplementary forms, etc. \n\nThe elements of the array are strings (i.e. \"first_name\") that refer to field name that can be targeted for search.\n","responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"tag_slug":{"$ref":"#/components/schemas/TagSlug"},"student_slug":{"$ref":"#/components/schemas/StudentSlug"},"form_slug":{"$ref":"#/components/schemas/FormSlug"}}}}}}}}}}}
```
## Search Students by Attributes
> Return student records that contain matching attribute/value pairs
```json
{"openapi":"3.0.1","info":{"title":"openapply","version":"3.0.0"},"tags":[{"name":"Search","description":"This page describes all the APIs relating to querying by student or parent attributes"}],"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/search":{"get":{"summary":"Search Students by Attributes","tags":["Search"],"operationId":"searchStudents","description":"Return student records that contain matching attribute/value pairs\n","parameters":[{"name":"student","in":"query","schema":{"type":"object"},"required":false,"description":"Search criteria for students"},{"name":"tag","in":"query","schema":{"type":"object"},"required":false,"description":"Search criteria for tags"},{"name":"field","in":"query","schema":{"type":"object"},"required":false,"description":"Search criteria for custom fields"},{"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":{"type":"object","properties":{"students":{"type":"array","items":{"$ref":"#/components/schemas/Student"}}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```