> 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":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","nullable":true},"address_ii":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"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","nullable":true},"custom_id":{"type":"string","nullable":true},"name":{"type":"string"},"parent_id":{"type":"string","nullable":true,"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},"deleted_at":{"type":"string","format":"date-time","nullable":true,"description":"When the parent was soft-deleted, e.g. as the losing record of a merge. `null` for live parents. Deleted parents are only returned when the `deleted_since` parameter is supplied."},"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","nullable":true},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","nullable":true}}}]}}},"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,"style":"deepObject","explode":true,"description":"Search criteria for parents, e.g. parent[first_name]=John"},{"name":"field","in":"query","schema":{"type":"object"},"required":false,"style":"deepObject","explode":true,"description":"Search criteria for custom fields, e.g. field[language]=French"}],"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":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":{"nullable":true,"type":"string","description":"A more specific classification under the parent `status`, used to indicate the detailed sub-status of the student."},"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},"deleted_at":{"type":"string","format":"date-time","nullable":true,"description":"When the student was soft-deleted, e.g. as the losing record of a merge. `null` for live students. Deleted students are only returned when the `deleted_since` parameter is supplied."},"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":"object","nullable":true,"description":"CRM Source Campaign the student is attributed to. Independent of utm.","properties":{"id":{"type":"integer"},"campaign":{"type":"string"},"source":{"type":"string"}}},"utm":{"type":"object","nullable":true,"description":"Marketing parameters captured when the student arrived through an ROI or Application form link. Null when nothing was captured or the school has no CRM module. Never falls back to source_campaign.","properties":{"source":{"type":"string","nullable":true},"medium":{"type":"string","nullable":true},"campaign":{"type":"string","nullable":true},"term":{"type":"string","nullable":true},"content":{"type":"string","nullable":true},"gclid":{"type":"string","nullable":true},"referrer_url":{"type":"string","nullable":true},"landing_url":{"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","nullable":true},{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","nullable":true}}}]}}},"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,"style":"deepObject","explode":true,"description":"Search criteria for students, e.g. student[first_name]=John"},{"name":"tag","in":"query","schema":{"type":"object"},"required":false,"style":"deepObject","explode":true,"description":"Search criteria for tags, e.g. tag[title]=VIP"},{"name":"field","in":"query","schema":{"type":"object"},"required":false,"style":"deepObject","explode":true,"description":"Search criteria for custom fields, e.g. field[language]=French"},{"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"}}}}}}}}}}}
```