---
openapi: 3.0.1
info:
  title: openapply
  version: 3.0.0
  description: |
    OpenApply Public REST API Version 3 set orchestrates the OpenApply School Administration Management System.

    Contact Support:
    Name: Faria Education Group Limited.
    Email: support@openapply.com
tags:
- name: Authentication
  description: The following endpoint provides the Oauth2 client credentials flow
- name: Students
  description: This page describes all the APIs relating to students.
- name: Parents
  description: This page describes all the APIs relating to parents.
- name: Relationships
  description: This page describes all the APIs relating to relationships.
- name: Reenrollments
  description: This page describes all the APIs relating to reenrollments.
- name: Staff
  description: This page describes all the APIs relating to staff members.
- name: Search
  description: This page describes all the APIs relating to querying by student or
    parent attributes
- name: Contacts
  description: This page describes all the APIs relating to contacts.
- name: Fees
  description: This page describes all the APIs relating to fees.
- name: Files
  description: This page describes all the APIs relating to files
- name: Events
  description: This page describes all the APIs relating to events.
- name: Agents
  description: This page describes all the APIs relating to agents
servers:
- url: https://api.openapply.com
  description: CAN region auth server
- url: https://api.openapply.cn
  description: CN region auth server
paths:
  "/api/v3/agents":
    get:
      summary: Get all Agents
      tags:
      - Agents
      parameters:
      - name: since_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: since_id
        in: query
        required: false
        description: Return results with an ID greater than the specified ID.
        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
      description: |
        Retrieves a list of all agents. Results are paginated.
        Use the `page` and `per_page` query parameters to control pagination.
      responses:
        '200':
          description: agents found
          content:
            application/json:
              examples:
                example:
                  value:
                    agents:
                    - id: 1
                      email: test@example.com
                      first_name:
                      last_name:
                      gender:
                      updated_at: '2025-02-17T00:00:00.000Z'
                      agency_name: test
                      profile_photo:
                      custom_fields: {}
                      student_ids: []
                    - id: 2
                      email: test2@example.com
                      first_name:
                      last_name:
                      gender:
                      updated_at: '2025-02-17T00:00:00.000Z'
                      agency_name: testttt
                      profile_photo:
                      custom_fields: {}
                      student_ids: []
                    meta:
                      pages: 1
                      page: 1
                      per_page: 50
  "/api/v3/agents/{id}":
    get:
      summary: Get an Agent
      tags:
      - Agents
      parameters:
      - name: id
        in: path
        required: true
        description: Serial database ID used to refer to a unique student record in
          OpenApply
        schema:
          type: integer
      description: 'Fetch an instance of a agent

        '
      responses:
        '200':
          description: agent found
          content:
            application/json:
              examples:
                example:
                  value:
                    agents:
                      id: 1
                      email: test@example.com
                      first_name:
                      last_name:
                      gender:
                      updated_at: '2025-02-17T00:00:00.000Z'
                      agency_name: test
                      profile_photo:
                      custom_fields: {}
                      student_ids: []
  "/oauth/token":
    post:
      summary: Get Bearer Token
      tags:
      - Authentication
      operationId: getBearerToken
      description: Exchange the credentials (client ID and client secret) for a bearer
        token. Find these details in OpenApply's API Manager
      security:
      - oauth2Auth: []
        oauth2AuthCN: []
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: your_access_token
                  token_type:
                    type: string
                    example: bearer
                  expires_in:
                    type: integer
                    example: 3600
                required:
                - access_token
                - token_type
                - expires_in
        '401':
          description: Unauthorized - Invalid client credentials
        '400':
          description: Bad Request - Missing or invalid parameters
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: client_credentials
              required:
              - grant_type
  "/api/v3/contacts":
    get:
      summary: Get all Contacts
      tags:
      - Contacts
      operationId: listContacts
      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
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    contacts:
                    - id: 1
                      first_name: Roland
                      last_name: Bayer
                      lead: Sign up for Admissions Information
                      email: kyle@jacobi.biz
                      avatar_url: "/assets/fallback/thumb_default_avatar-9af962b3cff94e1532ddd91a97e977b8461383e9f4e7e33dfd573942a9de5e45.png?v=1600757575"
                      representative: ''
                      add_by_school: false
                      source_campaign:
                        id: 8
                        campaign: Facebook - 2020 - 03
                        source: Facebook
                      contact_date: '2020-09-22'
                      converted: false
                      mailing_list: []
                      email_campaign: []
                      phone_number: ''
                      employer_company: ''
                      job_title: ''
                      campus:
                        id: 1
                        name: Chatham Campus
                      applied_academic_year: '2025'
                      applied_grade: '2'
                      tags:
                      - id: 84
                        title: EAL
                      agent:
                        id: 1
                        email: test@example.com
                        agency_name: test
                      archived_at:
                      students:
                      - id:
                        nationality:
                          alpha2: UM
                        name: test
                        last_name: account
                        gender:
                        birthday:
                      created_at: '2020-09-22T06:52:55.000Z'
                      updated_at: '2020-09-22T06:52:55.000Z'
                    meta:
                      page: 1
                      pages: 2
                      per_page: 50
    post:
      summary: Create a New Contact
      tags:
      - Contacts
      operationId: createContact
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    contacts:
                      id: 1
                      first_name: Roland
                      last_name: Bayer
                      lead: Sign up for Admissions Information
                      email: kyle@jacobi.biz
                      avatar_url: "/assets/fallback/thumb_default_avatar-9af962b3cff94e1532ddd91a97e977b8461383e9f4e7e33dfd573942a9de5e45.png?v=1600757575"
                      representative: ''
                      add_by_school: false
                      source_campaign:
                        id: 8
                        campaign: Facebook - 2020 - 03
                        source: Facebook
                      contact_date: '2020-09-22'
                      converted: false
                      mailing_list: []
                      email_campaign: []
                      phone_number: ''
                      employer_company: ''
                      job_title: ''
                      campus:
                        id: 1
                        name: Chatham Campus
                      applied_academic_year: '2025'
                      applied_grade: '2'
                      tags:
                      - id: 84
                        title: EAL
                      agent:
                        id: 1
                        email: test@example.com
                        agency_name: test
                      archived_at:
                      students:
                      - id:
                        nationality:
                          alpha2: UM
                        first_name: test
                        last_name: account
                        gender:
                        birthday:
                      created_at: '2020-09-22T06:52:55.000Z'
                      updated_at: '2020-09-22T06:52:55.000Z'
        '422':
          description: invalid source_campaign_id structure
          content:
            application/json:
              examples:
                example:
                  value:
                    error:
                    - source_campaign_id must be an integers
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                phone_number:
                  type: string
                email:
                  type: string
                employer_company:
                  type: string
                job_title:
                  type: string
                applied_academic_year:
                  type: string
                applied_grade:
                  type: string
                campus_id:
                  type: integer
                agent_id:
                  type: array
                  items:
                    type: integer
                tag_ids:
                  type: array
                  items:
                    type: integer
                students:
                  type: array
                  items:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      birthday:
                        type: string
                      gender:
                        type: string
                      nationality:
                        type: string
                source_campaign_id:
                  type: integer
              required:
              - first_name
              - last_name
              - phone_number
              - email
  "/api/v3/contacts/{id}":
    get:
      summary: Get a Contact
      tags:
      - Contacts
      operationId: getContact
      parameters:
      - name: id
        in: path
        description: Serial database ID that uniquely identifies a contact record
          in OpenApply
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    contacts:
                      id: 1
                      first_name: Roland
                      last_name: Bayer
                      lead: Sign up for Admissions Information
                      email: kyle@jacobi.biz
                      avatar_url: "/assets/fallback/thumb_default_avatar-9af962b3cff94e1532ddd91a97e977b8461383e9f4e7e33dfd573942a9de5e45.png?v=1600757575"
                      representative: ''
                      add_by_school: false
                      source_campaign:
                        id: 8
                        campaign: Facebook - 2020 - 03
                        source: Facebook
                      contact_date: '2020-09-22'
                      converted: false
                      mailing_list: []
                      email_campaign: []
                      phone_number: ''
                      employer_company: ''
                      job_title: ''
                      campus:
                        id: 1
                        name: Chatham Campus
                      applied_academic_year: '2025'
                      applied_grade: '2'
                      tags:
                      - id: 84
                        title: EAL
                      agent:
                        id: 1
                        email: test@example.com
                        agency_name: test
                      archived_at:
                      students:
                      - id:
                        nationality:
                          alpha2: UM
                        first_name: test
                        last_name: account
                        gender:
                        birthday:
                      created_at: '2020-09-22T06:52:55.000Z'
                      updated_at: '2020-09-22T06:52:55.000Z'
    put:
      summary: Update a Contact
      tags:
      - Contacts
      operationId: updateContact
      parameters:
      - name: id
        in: path
        description: Serial database ID that uniquely identifies a contact record
          in OpenApply
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    contacts:
                      id: 1
                      first_name: Roland
                      last_name: Bayer
                      lead: Sign up for Admissions Information
                      email: kyle@jacobi.biz
                      avatar_url: "/assets/fallback/thumb_default_avatar-9af962b3cff94e1532ddd91a97e977b8461383e9f4e7e33dfd573942a9de5e45.png?v=1600757575"
                      representative: ''
                      add_by_school: false
                      source_campaign:
                        id: 8
                        campaign: Facebook - 2020 - 03
                        source: Facebook
                      contact_date: '2020-09-22'
                      converted: false
                      mailing_list: []
                      email_campaign: []
                      phone_number: ''
                      employer_company: ''
                      job_title: ''
                      campus:
                        id: 1
                        name: Chatham Campus
                      applied_academic_year: '2025'
                      applied_grade: '2'
                      tags:
                      - id: 84
                        title: EAL
                      agent:
                        id: 1
                        email: test@example.com
                        agency_name: test
                      archived_at:
                      students:
                      - id:
                        nationality:
                          alpha2: UM
                        first_name: test
                        last_name: account
                        gender:
                        birthday:
                      created_at: '2020-09-22T06:52:55.000Z'
                      updated_at: '2020-09-22T06:52:55.000Z'
        '404':
          description: not_found
          content:
            application/json:
              examples:
                example:
                  value:
                    error:
                    - Contact not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                phone_number:
                  type: string
                email:
                  type: string
                employer_company:
                  type: string
                job_title:
                  type: string
                applied_academic_year:
                  type: string
                applied_grade:
                  type: string
                campus_id:
                  type: integer
                agent_id:
                  type: array
                  items:
                    type: integer
                tag_ids:
                  type: array
                  items:
                    type: integer
                students:
                  type: array
                  items:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                      birthday:
                        type: string
                      gender:
                        type: string
                      nationality:
                        type: string
                source_campaign_id:
                  type: integer
  "/api/v3/events":
    get:
      summary: Get all Events
      tags:
      - Events
      parameters:
      - name: from_date
        in: query
        schema:
          type: string
      - name: to_date
        in: query
        schema:
          type: string
      - 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
      operationId: listEvents
      responses:
        '200':
          description: events found
          content:
            application/json:
              examples:
                example:
                  value:
                    events:
                    - id: 1
                      title: August Open Day
                      date: '2018-08-28'
                      description: 'Join us for the our August Open Day at both campuses!Looking
                        forward to seeing you then! '
                      started_at: 9:30 AM
                      ended_at: 11:30 AM
                      capacity:
                      limit_per_registration:
                      published: true
                      repeatable: false
                      on_landing_page: true
                      event_type: OpenDay
                      duration: 45
                      allow_parent_to_cancel: true
                      cancel_deadline: no_deadline
                      updated_at: '2024-11-27T11:32:43.000Z'
                      created_at: '2012-07-20T08:53:33.000Z'
                      hours: []
                    meta:
                      pages: 1
                      page: 1
                      per_page: 50
  "/api/v3/events/{id}":
    get:
      summary: Get an Event
      tags:
      - Events
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: event found
          content:
            application/json:
              examples:
                example:
                  value:
                    event:
                      id: 1
                      title: August Open Day
                      date: '2018-08-28'
                      started_at: 9:30 AM
                      ended_at: 11:30 AM
                      capacity:
                      limit_per_registration:
                      repeatable: false
                      on_landing_page: true
                      event_type: OpenDay
                      duration: 45
                      allow_parent_to_cancel: true
                      cancel_deadline: no_deadline
                      updated_at: '2024-11-27T11:32:43.000Z'
                      created_at: '2012-07-20T08:53:33.000Z'
                      registrations:
                      - id: 47
                        event_id: 1
                        date: '2016-08-28'
                        time:
                        student_ids:
                        - 8
                        parent_id: 216
                        attendees_count: 1
                        state: scheduled
                        note:
                        host: Sharon Arese
                        campus: Chatham Campus
                        created_at: '2015-08-13T09:29:53.000Z'
                        updated_at: '2015-08-13T09:29:53.000Z'
                      hours: []
        '404':
          description: event not found
  "/api/v3/events/registrations":
    get:
      summary: List event registrations
      tags:
      - Events
      parameters:
      - name: from_date
        in: query
        schema:
          type: string
      - name: to_date
        in: query
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
      operationId: listEventRegistrations
      responses:
        '200':
          description: registrations found
          content:
            application/json:
              examples:
                example:
                  value:
                    registrations:
                    - id: 44
                      event_id:
                      date: '2016-08-20'
                      time: " 10:00 AM"
                      attendees_count: 1
                      state: completed
                      note: Tour went great!
                      host: Sharon Arese
                      campus: Chatham Campus
                      updated_at: '2015-08-13T09:29:52.000Z'
                      created_at: '2013-02-08T17:18:45.000Z'
                    - id: 47
                      event_id: 1
                      date: '2016-08-28'
                      time:
                      attendees_count: 1
                      state: scheduled
                      note:
                      host: Sharon Arese
                      campus: Chatham Campus
                      updated_at: '2015-08-13T09:29:53.000Z'
                      created_at: '2015-08-13T09:29:53.000Z'
                    meta:
                      pages: 1
                      page: 1
                      per_page: 50
  "/api/v3/events/{id}/attendance":
    get:
      summary: List event attendance
      tags:
      - Events
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: state
        in: query
        schema:
          type: string
      - name: campus
        in: query
        schema:
          type: string
      - name: attendance_status
        in: query
        schema:
          type: string
      responses:
        '200':
          description: attendance found
          content:
            application/json:
              examples:
                example:
                  value:
                    attendance:
                    - id: 1
                      status: attended
                      created_at: '2015-08-13T09:29:53.000Z'
                      updated_at: '2015-08-13T09:29:53.000Z'
                      student:
                        id: 8
                        custom_id: S12345
                        serial_number: SN12345
                      registration:
                        id: 1
                        state: scheduled
                        campus: Chatham Campus
                        parent:
                          id: 216
        '404':
          description: event not found
  "/api/v3/fees":
    get:
      summary: Get all Fees
      tags:
      - Fees
      operationId: listFees
      description: |
        Retrieves a list of all fees. Results are paginated.
        Use the `page` and `per_page` query parameters to control pagination.
      parameters:
      - name: since_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: issue_date
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
      - name: status_level
        in: query
        schema:
          type: string
      - 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:
              examples:
                example:
                  value:
                    payments:
                    - id: 422
                      invoice_status: Paid
                      type: Application
                      invoice_number: 1374
                      amount: '90.0'
                      issue_date: '2017-10-30'
                      due_date: '2017-11-19'
                      payment_method: cash
                      payment_date: '2016-08-12'
                      student:
                        id: 1
                        custom_id: '1'
                        application_id: '00000001'
                        serial_number: 1
                        enrollment_year: 2018
                        status: applied
                        status_level: Assessment Completed
                    meta:
                      pages: 1
                      total_pages: 1
                      per_page: 50
                      count: 1
        '422':
          description: unprocessable content
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid status and substatus combination
        '400':
          description: bad request
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid since_date format
  "/api/v3/students/{id}/fees":
    post:
      summary: Create a Fee for a Student
      tags:
      - Fees
      operationId: createFee
      description: 'Create a fee. Returns the unique `id` in the body as well as attributes
        if successful.

        '
      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:
        '201':
          description: created paid fee
          content:
            application/json:
              examples:
                example:
                  value:
                    id: 422
                    invoice_status: Paid
                    type: Application
                    invoice_number: 1374
                    amount: '90.0'
                    issue_date: '2017-10-30'
                    due_date: '2017-11-19'
                    payment_method: cash
                    payment_date: '2016-08-12'
                    student:
                      id: 1
                      custom_id: '1'
                      application_id: '00000001'
                      serial_number: 1
                      enrollment_year: 2018
                      status: applied
                      status_level: Assessment Completed
        '404':
          description: Fee template not found
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Fee template not found
        '422':
          description: Invalid params
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid params
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_fee_id:
                  type: integer
                  description: The database id of the asscociated fee template
                status:
                  type: string
                  enum:
                  - outstanding
                  - processing
                  - paid
                  - past_due
                  - refunded
                payment_date:
                  type: string
                  format: date
                payment_method:
                  type: string
                payment_reminder_sent_at:
                  type: string
                check_number:
                  type: string
                last4:
                  type: string
              required:
              - custom_fee_id
              example:
                custom_fee_id: 1
                status: 10
  "/api/v3/students/{id}/fees/{fee_id}":
    patch:
      summary: Update a Fee
      tags:
      - Fees
      operationId: updateFee
      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: fee_id
        in: path
        description: Serial database ID that uniquely identifies a fee record in OpenApply
        required: true
        schema:
          type: integer
      description: 'Fetch an instance of a fee

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    id: 422
                    invoice_status: Paid
                    type: Application
                    invoice_number: 1374
                    amount: '90.0'
                    issue_date: '2017-10-30'
                    due_date: '2017-11-19'
                    payment_method: cash
                    payment_date: '2016-08-12'
                    student:
                      id: 1
                      custom_id: '1'
                      application_id: '00000001'
                      serial_number: 1
                      enrollment_year: 2018
                      status: applied
                      status_level: Assessment Completed
        '400':
          description: Empty payload is not allowed
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Empty payload is not allowed
        '422':
          description: Invalid date
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid date
        '404':
          description: Fee not found
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Fee not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                issue_date:
                  type: string
                due_date:
                  type: string
                currency:
                  type: string
              example:
                amount: 100
                issue_date: '2025-02-15'
  "/api/v3/payments":
    get:
      summary: Get all Payments
      tags:
      - Fees
      operationId: listPayments
      description: Synconym for "Get all Fees". Included to ensure backward compatibility.
        Please use "Get all Fees" instead
      deprecated: true
      parameters:
      - name: since_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: issue_date
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
      - name: status_level
        in: query
        schema:
          type: string
      - 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:
              examples:
                example:
                  value:
                    payments:
                    - id: 422
                      invoice_status: Paid
                      type: Application
                      invoice_number: 1374
                      amount: '90.0'
                      issue_date: '2017-10-30'
                      due_date: '2017-11-19'
                      payment_method: cash
                      payment_date: '2016-08-12'
                      student:
                        id: 1
                        custom_id: '1'
                        application_id: '00000001'
                        serial_number: 1
                        enrollment_year: 2018
                        status: applied
                        status_level: Assessment Completed
                    meta:
                      pages: 1
                      total_pages: 1
                      per_page: 50
                      count: 1
        '422':
          description: unprocessable content
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid status and substatus combination
        '400':
          description: bad request
          content:
            application/json:
              examples:
                example:
                  value:
                    errors: Invalid since_date format
  "/api/v3/fees/templates":
    get:
      summary: Get all Fee Templates
      tags:
      - Fees
      operationId: listFeeTemplates
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    templates:
                    - id: 1
                      name: Apply Now
                      detail: ''
                      kind: application
                      currency: USD
                      amount: '90.0'
                      name_translation: 立刻申请
                      detail_translation: ''
                    meta:
                      pages: 1
                      total_pages: 1
                      per_page: 50
                      count: 1
  "/api/v3/students/{id}/files":
    get:
      summary: Get all Student's Files
      tags:
      - Files
      operationId: listStudentFiles
      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: since_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: deleted_since
        in: query
        required: false
        description: Return records that have been soft deleted since the given date
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: date_uploaded
        in: query
        schema:
          type: string
      - name: categories
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    files:
                    - id: 46
                      source: Attachment
                      name: International_Student_Testing.png
                      display_name: International_Student_Testing.png
                      date_uploaded: '2025-02-20T07:58:12.000Z'
                      size: 109115
                      uploaded_by:
                        id: 1
                        type: User
                      url: http://faria.lvh.me/api/v3/secure_download/attachments/46
                      categories:
                      - id: 25
                        name: general
                    - id: 9
                      source: DocumentSubmission
                      name: Tel_Invalid_OA.png
                      display_name: Tel_Invalid_OA.png
                      date_uploaded: '2015-08-20T06:33:48.000Z'
                      size: 254430
                      uploaded_by:
                        id: 294
                        type: Parent
                      url: http://faria.lvh.me/api/v3/secure_download/documents/9
                      categories:
                      - id: 25
                        name: general
                    - id: 85
                      source: FieldFileValue
                      name: DP_-_Student_-_CAS.pdf
                      display_name: DP_-_Student_-_CAS.pdf
                      date_uploaded: '2015-08-20T05:31:00.000Z'
                      size: 660160
                      uploaded_by:
                        id:
                        type:
                      url: http://faria.lvh.me/api/v3/secure_download/files/85
                      categories:
                      - id: 25
                        name: general
                    meta:
                      page: 1
                      pages: 1
                      per_page: 500
  "/api/v3/idat/results":
    post:
      summary: create idat result
      tags:
      - iDat
      parameters:
      - name: Authorization
        in: header
        schema:
          type: string
      responses:
        '200':
          description: successful
        '400':
          description: bad request
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                student_id:
                  type: integer
                result_url:
                  type: string
                  format: uri
                test_code:
                  type: string
                tested_at:
                  type: integer
                  description: Timestamp in seconds
              required:
              - student_id
              - result_url
              - test_code
              - tested_at
              example:
                student_id: 1
                result_url: http://example.com/result/1
                test_code: TEST123
                tested_at: 1633036800
  "/api/v3/parents":
    get:
      summary: Get all Parents
      tags:
      - Parents
      operationId: ListParents
      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_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: since_id
        in: query
        required: false
        description: Return results with an ID greater than the specified ID.
        schema:
          type: integer
      - name: child_ids
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  parents:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Parent"
                  meta:
                    type: object
                    properties:
                      pages:
                        type: integer
                      per_page:
                        type: integer
                      page:
                        type: integer
    post:
      summary: Create a parent
      tags:
      - Parents
      operationId: CreateOneParent
      description: 'Create a parent. Returns the unique `id` in the body as well as
        attributes if successful.

        '
      parameters:
      - name: fields
        in: query
        required: false
        schema:
          type: string
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Parent"
        '400':
          description: bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                example:
                  error: 'param is missing or the value is empty: parent'
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                example:
                  errors:
                  - First name is required
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ParentCreate"
        required: true
  "/api/v3/parents/{id}":
    get:
      summary: Get a Parent
      tags:
      - Parents
      operationId: getOneParent
      description: 'Fetch an instance of a parent

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Serial database ID used to refer to a unique parent record in
          OpenApply
        schema:
          type: integer
      - name: fields
        in: query
        required: false
        schema:
          type: string
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Parent"
        '404':
          description: parent not found
    patch:
      summary: Update a parent
      tags:
      - Parents
      operationId: UpdateOneParent
      description: 'Updates a parent

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Serial database ID used to refer to a unique parent record in
          OpenApply
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Parent"
        '404':
          description: parent not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                example:
                  error: Parent not found
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ParentUpdate"
  "/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.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  parent_slug:
                    "$ref": "#/components/schemas/ParentSlug"
                  form_slug:
                    "$ref": "#/components/schemas/FormSlug"
  "/api/v3/parents/search":
    get:
      summary: Search Parents
      tags:
      - Search
      operationId: searchParents
      description: 'Return parent records that contain matching attribute/value pairs

        '
      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
                example:
                  error: Invalid search parameters
  "/api/v3/students/{student_id}/reenrollments":
    get:
      summary: Get all Student's Reenrollments
      tags:
      - Reenrollments
      operationId: listStudentReenrollments
      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: year
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    reenrollments:
                    - id: 59
                      created_at: '2015-09-07T02:13:29.000Z'
                      updated_at: '2015-09-07T02:13:29.000Z'
                      deleted_at:
                      form:
                        id: 59
                      student:
                        id: 11
                        custom_id: '10'
                        application_id: '00000010'
                        serial_number: 10
                        status: Enrolled
                        status_level:
                      status:
                        name: Confirmed
                        updated_at: '2015-09-07T02:13:29.000Z'
                      year: 2019
                      grade: 9
                      active: true
                      acceptance_date: '2014-03-13'
                      fee:
                        amount: '550.0'
                      ignored_deadline: false
                    meta:
                      page: 1
                      pages: 1
                      per_page: 50
  "/api/v3/reenrollments":
    get:
      summary: Get All Reenrollments
      tags:
      - Reenrollments
      operationId: getAllReenrollments
      description: |
        Retrieves a list of all reenrollments. Results are paginated.
        Use the `page` and `per_page` query parameters to control pagination.
      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: decision_date
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
      - name: year
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    reenrollments:
                    - id: 138
                      created_at: '2016-06-12T00:00:00.000Z'
                      updated_at: '2016-06-12T00:00:00.000Z'
                      deleted_at:
                      form:
                        id: 138
                      student:
                        id: 459
                        custom_id: '314'
                        application_id: '00000314'
                        serial_number: 314
                        status: Enrolled
                        status_level:
                      status:
                        name: Pending
                        updated_at: '2016-06-12T00:00:00.000Z'
                      year: 2019
                      grade: 9
                      active: true
                      acceptance_date: '2017-06-12'
                      fee:
                        amount: '550.0'
                      ignored_deadline: false
                    - id: 141
                      created_at: '2016-06-25T00:00:00.000Z'
                      updated_at: '2016-06-25T00:00:00.000Z'
                      deleted_at:
                      form:
                        id: 141
                      student:
                        id: 460
                        custom_id: '315'
                        application_id: '00000315'
                        serial_number: 315
                        status: Enrolled
                        status_level:
                      status:
                        name: Pending
                        updated_at: '2016-06-25T00:00:00.000Z'
                      year: 2019
                      grade: 9
                      active: true
                      acceptance_date: '2017-06-25'
                      fee:
                        amount: '550.0'
                      ignored_deadline: false
                    meta:
                      page: 1
                      pages: 1
                      per_page: 50
  "/api/v3/reenrollments/{id}":
    put:
      summary: update reenrollment
      tags:
      - Reenrollments
      parameters:
      - name: Authorization
        in: header
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example:
                  value:
                    reenrollment:
                      id: 59
                      created_at: '2015-09-07T02:13:29.000Z'
                      updated_at: '2015-09-07T02:13:29.000Z'
                      deleted_at:
                      form:
                        id: 59
                      student:
                        id: 11
                        custom_id: '10'
                        application_id: '00000010'
                        serial_number: 10
                        status: Enrolled
                        status_level:
                      status:
                        name: Confirmed
                        updated_at: '2015-09-07T02:13:29.000Z'
                      year: 2019
                      grade: 9
                      active: true
                      acceptance_date: '2014-03-13'
                      fee:
                        amount: '550.0'
                      ignored_deadline: false
        '422':
          description: unprocessable entity
          content:
            application/json:
              examples:
                example:
                  value:
                    error: Invalid status
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                grade:
                  type: integer
                status_updated_at:
                  type: string
              example:
                status: Confirmed
                grade: 10
                status_updated_at: '2023-10-01T00:00:00Z'
  "/api/v3/relationships":
    get:
      summary: List All Relationships
      tags:
      - Relationships
      operationId: ListRelationships
      description: |
        Retrieve all student-parent relationships in the school.

        This endpoint returns a paginated list of students with their associated parent IDs,
        providing a mapping of family relationships within the school system.

        The response includes:
        - Student ID and their associated parent IDs
        - Pagination metadata

        This is useful for understanding family structures and parent-child relationships.
      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
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  relationships:
                    type: array
                    items:
                      type: object
                      properties:
                        parent_id:
                          type: integer
                          description: Unique identifier for the parent
                        student_ids:
                          type: array
                          items:
                            type: integer
                          description: Array of student IDs associated with this parent
                        relationships:
                          type: array
                          items:
                            type: object
                            properties:
                              student_id:
                                type: integer
                                description: Student ID
                              relationship:
                                type: string
                                description: Relationship role between parent and
                                  student
                          description: Array of relationship objects between parent
                            and students
                  meta:
                    type: object
                    properties:
                      pages:
                        type: integer
                        description: Total number of pages available
                      per_page:
                        type: integer
                        description: Number of records per page
                    required:
                    - pages
                    - per_page
                required:
                - relationships
                - meta
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Unauthorized access
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Access forbidden
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
  "/api/v3/relationships/parent/{id}":
    get:
      summary: Get a Parent's Child Relationships
      tags:
      - Relationships
      operationId: getParentRelationships
      description: 'Fetch the associated children to the given parent

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Serial database ID used to refer to a unique parent record in
          OpenApply
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  parent_id:
                    type: integer
                    description: Unique identifier for the parent
                  student_ids:
                    type: array
                    items:
                      type: integer
                    description: Array of student IDs associated with this parent
                  relationships:
                    type: array
                    items:
                      type: object
                      properties:
                        student_id:
                          type: integer
                          description: Student ID
                        relationship:
                          type: string
                          description: Relationship role between parent and student
                    description: Array of relationship objects between parent and
                      students
        '404':
          description: parent not found
    put:
      summary: Update a Parent-Student Relationship
      tags:
      - Relationships
      operationId: updateParentRelationships
      description: 'Update the relationships between a parent and their children.
        Accepts an array of relationship objects, each specifying a student_id and
        an optional relationship role.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Serial database ID used to refer to a unique parent record in
          OpenApply
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  student_ids:
                    type: array
                    items:
                      type: integer
                    description: Array of student IDs associated with this parent
                  relationships:
                    type: array
                    items:
                      type: object
                      properties:
                        student_id:
                          type: integer
                          description: Student ID
                        relationship:
                          type: string
                          description: Relationship role between parent and student
                    description: Array of relationship objects between parent and
                      students
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                required:
                - errors
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                relationships:
                  type: array
                  items:
                    type: object
                    properties:
                      student_id:
                        type: integer
                      relationship:
                        type: string
                        nullable: true
                        description: Relationship role (optional)
                    required:
                    - student_id
              required:
              - relationships
        required: true
  "/api/v3/relationships/student/{id}":
    get:
      summary: Get a Student's Parent Relationships
      tags:
      - Relationships
      operationId: getStudentRelationships
      description: 'Fetch the associated parents and relationship roles for the given
        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:
                type: object
                properties:
                  parent_id:
                    type: integer
                    description: Unique identifier for the parent
                  student_ids:
                    type: array
                    items:
                      type: integer
                    description: Array of student IDs associated with this parent
                  relationships:
                    type: array
                    items:
                      type: object
                      properties:
                        student_id:
                          type: integer
                          description: Student ID
                        relationship:
                          type: string
                          description: Relationship role between parent and student
                    description: Array of relationship objects between parent and
                      students
        '404':
          description: student not found
  "/api/v3/staff":
    get:
      summary: List all Staff Members
      tags:
      - Staff
      operationId: ListStaff
      description: |
        Retrieve all active staff members in the school.

        This endpoint returns a paginated list of staff members with their basic information
        including name, email, department, and contact details.

        Staff members are users who have been assigned to a department and are active
        in the school system.

        The response includes:
        - Staff member details (name, email, title, phone, etc.)
        - Department information
        - Pagination metadata
      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_date
        in: query
        required: false
        description: Return results updated since the specified date, in UTC timezone
        schema:
          type: string
          format: date_time
          example: '2025-01-01T00:00:00Z'
      - name: since_id
        in: query
        required: false
        description: Return staff members with ID greater than this value
        schema:
          type: integer
      - name: department_id
        in: query
        required: false
        description: Filter staff members by specific department ID
        schema:
          type: integer
      - name: department_ids
        in: query
        required: false
        description: Comma-separated list of department IDs to filter by
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  staff:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Staff"
                  meta:
                    type: object
                    properties:
                      pages:
                        type: integer
                      per_page:
                        type: integer
                      count:
                        type: integer
                required:
                - staff
                - meta
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Unauthorized access
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Access forbidden
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
  "/api/v3/staff/{id}":
    get:
      summary: Get a Staff Member
      tags:
      - Staff
      operationId: getOneStaff
      description: |
        Retrieve detailed information about a specific staff member.

        This endpoint returns comprehensive information about a staff member
        including their personal details, department assignment, and contact information.

        The staff member must be active and assigned to a department to be accessible
        through this endpoint.
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the staff member
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                example_0:
                  value:
                    staff:
                      id: 123
                      first_name: John
                      last_name: Smith
                      email: john.smith@school.com
                      title: Mathematics Teacher
                      phone: "+1-555-123-4567"
                      department_id: 456
                      position: Teacher
                      created_at: '2024-01-15T10:30:00Z'
                      updated_at: '2024-01-15T10:30:00Z'
              schema:
                "$ref": "#/components/schemas/Staff"
        '404':
          description: Staff member not found
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Staff member not found
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                example_0:
                  value:
                    error: Unauthorized access
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
  "/api/v3/students":
    get:
      summary: Get All Students
      tags:
      - Students
      operationId: listStudents
      description: |
        Retrieves a list of all students. Results are paginated.
        Use the `page` and `per_page` query parameters to control pagination.
      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
          example: '2025-01-01T00:00:00Z'
      - 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
          example: paid
      - name: enrollment_year
        in: query
        required: false
        description: Filter students by enrollment year
        schema:
          type: string
          example: '2023'
      - name: parent_ids
        in: query
        required: false
        description: Filter students by parent IDs
        schema:
          type: string
          example: '1,2,3'
      - name: fields
        in: query
        required: false
        schema:
          type: string
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      - name: link_fields
        in: query
        required: false
        schema:
          type: string
          example: id,email,custom_fields(language)
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  students:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Student"
                  meta:
                    type: object
                    properties:
                      pages:
                        type: integer
                      per_page:
                        type: integer
                      count:
                        type: integer
    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.

        '
      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
  "/api/v3/students/{id}":
    get:
      summary: Get a Student
      tags:
      - Students
      operationId: getOneStudent
      description: 'Fetch an instance of a 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
      - name: fields
        in: query
        required: false
        schema:
          type: string
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Student"
        '404':
          description: student not found
    patch:
      summary: Update a student
      tags:
      - Students
      operationId: UpdateOneStudent
      description: 'Updates a 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
      - name: fields
        in: query
        required: false
        schema:
          type: string
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      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
                example:
                  error: Student not found
        '422':
          description: unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/StudentUpdate"
  "/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
                example:
                  error: Student not found
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                example:
                  error: Invalid status or status level
      requestBody:
        content:
          application/json:
            schema:
              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)
        description: Status update parameters
  "/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
  "/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"
  "/api/v3/students/search":
    get:
      summary: Search Students by Attributes
      tags:
      - Search
      operationId: searchStudents
      description: 'Return student records that contain matching attribute/value pairs

        '
      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
          example: id,name,custom_fields(parent_guardians(id,email))
        description: 'Comma-separated list of fields to include in the response. Supports
          nested fields using parentheses

          '
      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
                example:
                  error: Invalid search parameters
  "/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.

        Filterable by status updated_at (since_date_to_status) and enrollment_year.
      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
security:
- bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2Auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.openapply.com/oauth/token
          scopes: {}
    oauth2AuthCN:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.openapply.cn/oauth/token
          scopes: {}
  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
        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
        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
        updated_at:
          type: string
          format: date-time
          nullable: true
        latest_activity_date:
          type: string
          format: date-time
          nullable: true
        nationality:
          type: string
          nullable: true
        grade:
          type: string
          description: The grade
        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
        reenrollments:
          type: array
          items:
            "$ref": "#/components/schemas/Reenrollment"
        custom_fields:
          "$ref": "#/components/schemas/CustomFields"
    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"
    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
        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
    ParentUpdate:
      type: object
      properties:
        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
    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
        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
    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
    ParentCreate:
      type: object
      properties:
        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
      required:
      - first_name
      - last_name
      - email
    Relationship:
      type: object
      properties:
        parent_id:
          type: integer
          description: Unique identifier for the parent
        student_ids:
          type: array
          items:
            type: integer
          description: Array of student IDs associated with this parent
        relationships:
          type: array
          items:
            type: object
            properties:
              student_id:
                type: integer
                description: Student ID
              relationship:
                type: string
                description: Relationship role between parent and student
          description: Array of relationship objects between parent and students
      required:
      - student_id
      - parent_ids
    Staff:
      type: object
      properties:
        id:
          type: integer
          description: Serial database ID that uniquely identifies the staff record
        isams_id:
          type: string
          nullable: true
          description: External iSAMS system identifier
        managebac_user_id:
          type: string
          nullable: true
          description: External ManageBac system identifier
        email:
          type: string
          description: Staff member email address
        first_name:
          type: string
          description: Staff member first name
        last_name:
          type: string
          description: Staff member last name
        title:
          type: string
          nullable: true
          description: Staff member job title or position
        properties:
          type: object
          nullable: true
          description: Additional staff properties
          properties:
            phone:
              type: string
              nullable: true
              description: Staff member phone number
        admin:
          type: boolean
          description: Whether the staff member has admin privileges
        can_admit_and_enroll:
          type: boolean
          description: Whether the staff member can admit and enroll students
        can_edit_notes_and_files:
          type: boolean
          description: Whether the staff member can edit notes and files
        can_read_only:
          type: boolean
          description: Whether the staff member has read-only access
        admission_contact:
          type: boolean
          description: Whether the staff member is an admission contact
        type:
          type: string
          description: Staff member type
        department:
          type: object
          nullable: true
          description: Department information
          properties:
            id:
              type: integer
              description: Department ID
            name:
              type: string
              description: Department name
        using_sso:
          type: boolean
          description: Whether the staff member uses single sign-on
        email_verified:
          type: boolean
          description: Whether the email address has been verified
        last_sign_in_at:
          type: string
          format: date-time
          nullable: true
          description: Last sign-in timestamp
        created_at:
          type: string
          format: date-time
          description: Record creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Record last update timestamp
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Record deletion timestamp
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Record archival timestamp
        otp_required_for_login:
          type: boolean
          nullable: true
          description: Whether OTP is required for login
        token_last_time_used_at:
          type: string
          format: date-time
          nullable: true
          description: Last time an API token was used
    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
    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
    CustomFieldValue:
      oneOf:
      - type: string
      - type: array
        items:
          type: object
          additionalProperties:
            type: string
    CustomFields:
      type: object
      additionalProperties:
        "$ref": "#/components/schemas/CustomFieldValue"
    TagSlug:
      type: array
      items:
        type: string
    StudentSlug:
      type: array
      items:
        type: string
    ParentSlug:
      type: array
      items:
        type: string
    FormSlug:
      type: array
      items:
        type: object
        additionalProperties:
          type: string
          nullable: true
