# 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](/integrations-portal/openapply/recipes/pulling-custom-fields.md)

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:

```json
{
  "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)
```

2. 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(…))
```

3. 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:

```json
{
    "linked": [
        {
            "id": 1,
            "first_name": "Happy",
            "last_name": "Parent",
            "mobile_phone_number": "+99 999 9999",
            "parent_role": "Mother",
            "custom_fields": {
                "treat_parent_as_emergency_contact": "Yes"
            }            
            // …
        },
        {
            "id": 2,
            "first_name": "Smiling",
            "last_name": "Parent",
            "mobile_phone_number": "+99 999 9999",
            "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)
```

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

```
id,parent_ids
```

3. 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.fariaedu.com/integrations-portal/openapply/recipes/using-field-mask.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.