Using Field Mask

Problem Statement

OpenApply's flexible architecture allows schools to create custom fields to manage their data. Its API exposes all these custom fields and their values per student through the "Get all Students" endpoint. This flexibility enables schools to efficiently orchestrate their data management needs.

However, calling the "Get all Students" endpoint to retrieve all values for every student is not always optimal. Often, the calling application only needs specific fields, such as id, first_name, and just a few custom fields, such as lunch_paid_by.

To learn how to programmatically fetch the names of custom fields, please see Pulling Custom Fields

By including the fields query parameter in the API call, applications can retrieve only the required fields, significantly reducing response times.

By including the linked_fields query parameter in the API call, applications can select to only retrieve specific fields of the linked parents and guardians.

Our testing shows that using field masks can improve response times by more than a second.

Tutorial: Fields

Understanding the Structure

To determine the exact notation, we inspect a sample student record:

{
  "id": 123,
  "custom_id": "S12345",
  // ... other fields
  "custom_fields": {
     "bus_paid_by": "Parents",
     "immunization_record": [
        {
           "date": "2000-01-01",
           "kind": "Measles"
        }
     ]
  }
}

Building the Request

Start from the inner-most and work our way out.

1. Suppose we want to extract only the kind of immunizations. We can declare this in this way:

immunization_record(kind)

1. Also we need to include bus_paid_by as well, both of which are nested inside custom_fields body:

custom_fields(bus_paid_by,immunization_record(…))

1. For the student record, we need id and custom_id:

id, custom_id

Since immunization and bus records are nested inside custom_fields, we include this key at the same level it appears in the response:

id,custom_id,custom_fields(...)

Final query parameter (formatted for clarity):

?
  fields=
    id,custom_id,
    custom_fields(
      bus_paid_by,
      immunization_record(
        kind
      )
    )

Example request

GET https://api.openapply.com/api/v3/students?fields=id,custom_id,custom_fields(bus_paid_by,immunization_record(date)))

Tutorial: Linked Fields

Understanding the structure

The below shows the response structure for Get all Students, demonstrating how student and parent relationships are represented in the response. It shows two students, Happy Student and Smiling Student, linked to one parent each. This is made visible via the parent_ids list and how they correspond in the linked > id path:

{
    "linked": [
        {
            "id": 1,
            "first_name": "Happy",
            "last_name": "Parent",
            "mobile_phone_number": "[phone]",
            "parent_role": "Mother",
            "custom_fields": {
                "treat_parent_as_emergency_contact": "Yes"
            }            
            // …
        },
        {
            "id": 2,
            "first_name": "Smiling",
            "last_name": "Parent",
            "mobile_phone_number": "[phone]",
            "parent_role": "Father",
            "custom_fields": {
                "treat_parent_as_emergency_contact": "Yes"
            }
            // ..
        }
    ],
    "students": [
        {
            "id": 9,
            "first_name": "Happy",
            "last_name": "Student",
            "parent_ids": [
                1
            ]
            // ..
        },
        {
            "id": 9,
            "first_name": "Smiling",
            "last_name": "Student",
            "parent_ids": [
                2
            ]
            // ..
        }
    ]
}

Building the Request

Our application wants to fetch the mobile phone numbers of the parents who are emergency contacts.

1. We only need the id , mobile_phone_number, and treat_as_emergency_contact fields to be returned in the linked body:

id,mobile_phone_number,custom_fields(treat_as_emergency_contact)

2. For students, say for example we only want the ids:

id,parent_ids

1. Combine both (formatted for clarity):

?
  linked_fields=
    id,mobile_phone_number,
    custom_fields(
      treat_as_emergency_contact
    ),
&
  fields=
    id,parent_ids

Common Issues & Troubleshooting

When using the fields query parameter, OpenApply may return a full response instead of the expected filtered data. This can happen in the following cases:

• Misspelled fields (e.g., parent_guardians instead of parent_guardian)

• Incorrect nesting levels (e.g., parent_guardian() instead of custom_fields(parent_guardian(...)))

• Mismatched or missing parentheses

• Any parsing failure in the fields parameter

Note: The API does not return an error message when the fields parameter fails validation. Instead, it defaults to returning a full response.

Recommendation

Using a field mask offers significant benefits for both clients and the server:

• Improved performance by reducing response times

• Lower API request load, leading to better efficiency