> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/openapply/recipes/updating-custom-fields.md).

# Updating Custom Fields

## Problem statement

Some integrations need more than read access to custom fields. They need to discover the field schema, validate allowed values, update student or parent records, and manage grouped field records.

### Before you start

Make sure your integration can authenticate against OpenApply v3.

See [OpenApply v3 API Authentication](/integrations-portal/openapply/recipes/openapply-v3-api-authentication.md).

If you only need to read custom field values from student or parent records, start with [Pulling Custom Fields](/integrations-portal/openapply/recipes/pulling-custom-fields.md).

### Recommended workflow

#### 1. Discover the available fields

Use `GET /api/v3/fields` to fetch the current field schema for the school.

This is the best starting point when your integration should adapt to each school's configuration instead of hardcoding field names.

```bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://school.openapply.com/api/v3/fields"
```

Use the endpoint's query parameter shown in the API reference when you want to limit results to one record type.

See [Fields](/integrations-portal/openapply/public-rest-apis/v3/fields.md).

#### 2. Inspect one field before writing to it

Use `GET /api/v3/fields/{id}` to fetch metadata for one field.

This is especially useful for:

* select fields with predefined options
* grouped fields with child fields
* validation before you send updates

```bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://school.openapply.com/api/v3/fields/12345"
```

Review the field's type, slug, and available options before building the payload.

#### 3. Update student custom fields

Use `PATCH /api/v3/students/{id}/custom_fields` to write custom field values to a student record.

Build the `custom_fields` payload from the identifiers returned by the fields endpoints.

```bash
curl -X PATCH \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://school.openapply.com/api/v3/students/123/custom_fields" \
  -d '{
    "custom_fields": {
      "<field_identifier>": "<value>"
    }
  }'
```

For grouped fields, send an array of records.

```json
{
  "custom_fields": {
    "<group_field_identifier>": [
      {
        "<child_field_identifier>": "<value>",
        "<child_field_identifier_2>": "<value>"
      }
    ]
  }
}
```

See [Students](/integrations-portal/openapply/public-rest-apis/v3/students.md).

#### 4. Update parent custom fields

Use `PATCH /api/v3/parents/{id}/custom_fields` for parent or guardian records.

The payload shape matches the student custom fields endpoint.

```bash
curl -X PATCH \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://school.openapply.com/api/v3/parents/456/custom_fields" \
  -d '{
    "custom_fields": {
      "<field_identifier>": "<value>"
    }
  }'
```

See [Parents](/integrations-portal/openapply/public-rest-apis/v3/parents.md).

#### 5. Delete one grouped student record

Use `DELETE /api/v3/students/{id}/custom_fields/{field_id}/records/{record_id}` when you need to remove one item from a grouped field without changing the other records.

This is useful for grouped data such as previous schools or similar repeatable entries.

```bash
curl -X DELETE \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://school.openapply.com/api/v3/students/123/custom_fields/789/records/321"
```

#### 6. Manage options for select fields

If your integration also manages the field configuration, use the field option endpoints:

* `POST /api/v3/fields/{field_id}/options`
* `PATCH /api/v3/fields/{field_id}/options/{id}`
* `DELETE /api/v3/fields/{field_id}/options/{id}`

Example create request:

```bash
curl -X POST \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://school.openapply.com/api/v3/fields/12345/options" \
  -d '{
    "option": {
      "name": "New option"
    }
  }'
```

### Practical guidance

#### Read first, then write

Do not assume the same field exists across schools.

Always start by discovering fields for the current school, then build your write payload from that response.

#### Validate option fields before updating

For select-style fields, fetch the field detail first.

That gives you the allowed options and helps avoid failed writes.

#### Treat grouped fields as structured data

Grouped fields are not single string values.

They contain one or more records, and each record contains child fields.

#### Keep payloads narrow

Only send the custom fields you want to change.

This reduces the risk of overwriting unrelated values.

### Related pages

* [OpenApply v3 API Authentication](/integrations-portal/openapply/recipes/openapply-v3-api-authentication.md)
* [Pulling Custom Fields](/integrations-portal/openapply/recipes/pulling-custom-fields.md)
* [Using Field Mask](/integrations-portal/openapply/recipes/using-field-mask.md)
* [Fields](/integrations-portal/openapply/public-rest-apis/v3/fields.md)