Custom Fields API

In this Section:

• Discovering fields
• Discovering options
• Writing values
• Examples
• Updating and clearing
• Rules and validation

---

Custom fields let an organisation attach extra structured data to records such as students, enrolments, intakes, contacts and organisations. Each field has a type (text, number, date, time, check, drop, multi, link or textarea) and is scoped to a particular record type — for example a Student field cannot be written against an Enrolment.

This article covers the API surface for reading custom field definitions and writing custom field values. Field definitions themselves are created and edited in the SELMA admin UI — there is no POST on /api/custom_fields.

---

Discovering fields

GET /api/custom_fields returns every field defined for your account. Each item exposes the field id, label, api_name, the type (with a code such as drop or text), the object it belongs to (e.g. S for Student), and — for drop and multi fields — a customFieldOptions array of option IRIs.

GET /api/custom_fields/19142

{
  "@id": "/api/custom_fields/19142",
  "id": 19142,
  "label": "Favourite Colour",
  "api_name": "favourite_colour",
  "custom_field_type": { "code": "drop", … },
  "customFieldOptions": [
    "/api/custom_field_options/60792",
    "/api/custom_field_options/60793",
    "/api/custom_field_options/60794"
  ]
}

Filter the collection by api_name, label, custom_field_object, or custom_field_type:

GET /api/custom_fields?api_name=favourite_colour

---

Discovering options

For drop and multi fields, dereference any IRI from the field’s customFieldOptions array, or query the collection directly:

GET /api/custom_field_options?custom_field=19142

{
  "totalItems": 3,
  "member": [
    {
      "@id": "/api/custom_field_options/60792",
      "id": 60792,
      "custom_field": "/api/custom_fields/19142",
      "code": "red",
      "name": "Red",
      "value": "red",
      "sort_order": 1,
      "active": true
    },
    …
  ]
}

Also filterable by code and active.

---

Writing values

A custom field value binds a field to a single parent record (such as a student or enrolment) and carries the user’s input in selected_value.

Three things to send on every POST:

• custom_field — IRI of the field definition.
• One parent IRI — exactly one of student, enrolment, enrolment_component, intake, intake_component, programme, component, campus, contact, organisation, class, sysuser, application, or placement. It must match the field’s custom_field_object.
• selected_value — a flat value whose shape depends on the field type.

Shapes for selected_value:

• text / textarea / link / number — a scalar string.
• date — "YYYY-MM-DD".
• time — "HH:MM" or "HH:MM:SS".
• check — "0", "1", "true" or "false".
• drop — a single CustomFieldOption IRI.
• multi — an array of CustomFieldOption IRIs.

---

Examples

Text field on a Student

POST /api/custom_field_values
Content-Type: application/ld+json

{
  "custom_field":   "/api/custom_fields/19140",
  "student":        "/api/students/800990683",
  "selected_value": "Jane Doe"
}

Drop field on a Student

POST /api/custom_field_values

{
  "custom_field":   "/api/custom_fields/19142",
  "student":        "/api/students/800990683",
  "selected_value": "/api/custom_field_options/60793"
}

Multi field on an Enrolment

POST /api/custom_field_values

{
  "custom_field":   "/api/custom_fields/19150",
  "enrolment":      "/api/enrolments/12345",
  "selected_value": [
    "/api/custom_field_options/60792",
    "/api/custom_field_options/60794"
  ]
}

---

Updating and clearing

Use PATCH with application/merge-patch+json to change just the value:

PATCH /api/custom_field_values/132719
Content-Type: application/merge-patch+json

{ "selected_value": "/api/custom_field_options/60792" }

To clear a value, send null:

PATCH /api/custom_field_values/132719

{ "selected_value": null }

---

Rules and validation

• Exactly one parent IRI per value — zero or two is a 422.
• The parent’s record type must match the field’s custom_field_object.
• For drop and multi, the supplied option IRI(s) must belong to that field. A 422 with “…” is not a valid option for this custom field. is returned otherwise.
• Mandatory fields reject empty selected_value.
• max_length and validation_regex from the field definition are enforced on text-shaped values.

NOTE: Field definitions and their options are managed in the SELMA admin UI. The API exposes them as read-only resources so integrations can discover what’s available and write values against them.