Registration Configuration API

Overview

GET /api/utilities/registration-configuration

Returns a complete snapshot of all configuration values that affect the registration form for the current LEAD instance. This is useful for understanding which registration features are active and what data drives the form, without needing SSH access to read .env values.

Auth: Requires an authenticated admin user (non-admins receive 403).

Response Structure

The response is a flat JSON object combining three categories of data:

Registration Config Variables

These come from config('fivable.registration.*') and are driven by .env values.

Key	Type	Default	Description

Key	Type	Default	Description
`allow_city_other`	`boolean`	`false`	Whether an "Other" option appears in the city dropdown
`allow_role_other`	`boolean`	`false`	Whether an "Other" option appears in the role dropdown
`ask_additional_languages`	`boolean`	`false`	Whether the form asks for additional languages spoken
`ask_address`	`boolean`	`false`	Whether the form collects a full address
`ask_address_state_only`	`boolean`	`false`	Whether only a state field is shown (instead of full address)
`ask_city_first`	`boolean`	`false`	Whether city selection appears before place selection (city drives available places)
`ask_language`	`boolean`	`false`	Whether the form asks for a preferred language
`ask_organization_name`	`boolean`	`false`	Whether the form asks for an organization name
`ask_phone`	`boolean`	`false`	Whether the form collects a phone number
`default_group_id`	`int\|null`	`null`	Auto-assigns registrants to this group (skips group selection)
`default_lp_id`	`int\|null`	`null`	Auto-assigns registrants to this learning path
`dob_min_age`	`int`	`13`	Minimum age in years for date-of-birth validation
`dont_collect_date_of_birth`	`boolean`	`false`	Whether to skip collecting date of birth entirely
`email_label`	`string\|null`	`null`	Custom label text for the email field (e.g., "Work Email")
`first_group_with_location_add_outside`	`boolean`	`false`	Whether an "Outside" / not-affiliated option appears in the first place selection
`first_location_type_ids`	`array<int>`	`[]`	Location type IDs shown in the first place-selection step
`group_intro_html`	`string\|null`	`null`	HTML content displayed above group/place selection
`intro_html`	`string\|null`	`null`	HTML content displayed at the top of the registration form
`place_selection_prompts`	`array<object>`	`[]`	Configured place-selection prompt steps (see Place Selection Prompts below)
`role_options`	`array<string>\|null`	`null`	Available role options in registration (null = no role selection)
`uses_mailtrap`	`boolean`	`false`	Indicates if the instance uses Mailtrap (vs sending real mail or logging)

Basic Config Variables

These come from config('fivable.*').

Key	Type	Default	Description

Key	Type	Default	Description
`additional_registration_profile_fields`	`array<object>`	`[]`	Extra profile fields added to registration (custom per instance)
`flodesk_opt_in_label`	`string\|null`	`null`	Label text used for Flodesk opt-in checkbox
`has_flodesk`	`boolean`	`false`	Whether Flodesk email integration is configured (drives opt-in checkbox)
`has_twilio`	`boolean`	`false`	Whether Twilio SMS is configured
`has_twilio_premium`	`boolean`	`false`	Whether Twilio premium SMS is enabled
`honorifics`	`array<string>`	`["Dr.","Mr.","Mrs.",...]`	Available salutation/honorific options
`terms_conditions_url`	`string\|null`	`null`	URL to terms & conditions (if set, a T&C checkbox appears)

Dynamic Form Data

These are computed from the database at request time.

Key	Type	Description

Key	Type	Description
`cities`	`array<string>`	Available cities derived from groups with locations. Empty if `ask_city_first` is `false`. Includes "Other" if `allow_city_other` is `true`.
`group_types`	`array<GroupType>`	Group types marked `display_on_registration = true` that have joinable groups. Each includes its nested `groups` sorted by name.
`groups_with_location`	`array<Group>`	All groups eligible for registration that have a physical location.
`learningPathOptions`	`array<LearningPath>`	Learning paths with `visibility` containing "registration" that are published (or unpublished). Each includes `groups_initialized` with `group_type`.
`marriagePrepIds`	`array<int>`	IDs of learning paths with `type = "marriage_prep"` (drives special form behavior).
`place_selection_prompts`	`array<object>`	Resolved place-selection prompts with actual group data. Each prompt has `location_type_ids`, `groups` (with `id` and `name_city`), and optionally a `selected_id`. Overrides the config value of the same key.
`roles`	`array<string>`	Resolved role options from config, with "Other" appended if `allow_role_other` is `true`. Empty array if no `role_options` configured.
`language_options`	`array<object>`	Available languages based on `SUPPORTED_LANGUAGES`. Each entry has `label` (e.g., "English") and `value` (e.g., "en-US").

Example Request

curl -X GET https://<instance>/api/utilities/registration-configuration \
  -H "Authorization: Bearer <token>"

Example Response (Abbreviated)

{
  "allow_city_other": false,
  "allow_role_other": true,
  "ask_additional_languages": false,
  "ask_address": false,
  "ask_address_state_only": false,
  "ask_city_first": true,
  "ask_language": true,
  "ask_organization_name": false,
  "ask_phone": true,
  "default_group_id": null,
  "default_lp_id": 42,
  "dob_min_age": 13,
  "dont_collect_date_of_birth": false,
  "email_label": "Work Email",
  "first_group_with_location_add_outside": false,
  "first_location_type_ids": [1, 3],
  "group_intro_html": "<p>Select your parish below</p>",
  "intro_html": null,
  "place_selection_prompts": [],
  "role_options": ["Teacher", "Catechist", "Parent"],
  "additional_registration_profile_fields": [],
  "flodesk_opt_in_label": null,
  "has_flodesk": false,
  "has_twilio": true,
  "has_twilio_premium": false,
  "honorifics": ["Dr.", "Mr.", "Mrs.", "Ms.", "Sr.", "Fr.", "Br.", "Msgr.", "Deacon"],
  "terms_conditions_url": "https://example.com/terms",
  "cities": ["Chicago", "Milwaukee", "Other"],
  "group_types": [],
  "groups_with_location": [],
  "learningPathOptions": [],
  "marriagePrepIds": [],
  "roles": ["Teacher", "Catechist", "Parent", "Other"],
  "language_options": [
    {"label": "English", "value": "en-US"},
    {"label": "Spanish (Spain)", "value": "es-ES"}
  ]
}

Field Visibility & Behavior Matrix

This section documents exactly which config values control the visibility, behavior, and preset values of each form field. Use this to understand what the registration form looks like for a given configuration.

Always-Visible Fields

These fields are always present on the registration form regardless of configuration:

Field	Config Interactions

Field	Config Interactions
First Name	None — always shown, always required
Last Name	None — always shown, always required
Email	Label text changes if `email_label` is set (e.g., "Work Email" instead of "Email")
Password	None — always shown, always required, minimum 8 characters
Fivable Terms of Service	None — always shown, always required

Conditionally-Visible Fields

Field	Visible When	Preset Value / Special Behavior

Field	Visible When	Preset Value / Special Behavior
Title / Salutation	`honorifics` is a non-empty array	Options populated from `honorifics`. Rendered as radio buttons. Not required.
Date of Birth	`dont_collect_date_of_birth = false`	Validates against `dob_min_age` (shows error "Must be at least {N} years of age" if underage). Required.
Age Confirmation Checkbox	`dont_collect_date_of_birth = true`	Replaces DOB field. Text reads "I confirm that I am {dob_min_age} years of age or older". Required.
Language	`ask_language = true` AND `language_options` is non-empty	Dropdown populated from `language_options`. Pre-selected to user's browser language (`navigator.language`).
Additional Languages	`ask_language = true` AND `ask_additional_languages = true` AND `language_options` is non-empty	Multi-select dropdown. Shows all `language_options` except the currently selected primary language.
Street Address 1 & 2	`ask_address = true`	Two text fields. Not required.
City (text input)	`ask_address = true`	Free-text city field as part of the full address. Not required.
City (dropdown)	`ask_city_first = true` AND `groups_with_location` is non-empty	Dropdown populated from `cities`. Label is "Workplace City". Disabled if a place is already pre-selected. Required. Selecting a city filters the Place dropdown to groups in that city.
State	`ask_address = true` OR `ask_address_state_only = true`	Dropdown of US states. Not required.
ZIP Code	`ask_address = true`	Text field. Not required. Only shown with full address, not with state-only.
Place (dropdown)	`groups_with_location` is non-empty AND user hasn't selected "Other" city	Dropdown populated from `groups_with_location`. Label is "Workplace" when `ask_city_first = true`, otherwise "Place". Pre-selected to `default_group_id` if set. Disabled until a city is chosen (when `ask_city_first = true`). If `first_group_with_location_add_outside = true`, an "Outside of the Diocese" option is appended. Required.
Place (manual text input)	`ask_city_first = true` AND user selects "Other" from city dropdown	Replaces the Place dropdown. Label is "City, State, Workplace". Free-text entry. Required.
Role	`roles` is a non-empty array (derived from `role_options`)	Dropdown populated from `roles`. Required.
Specify Role (text input)	`roles` contains "Other" AND user selects "Other" from the Role dropdown	Free-text entry for custom role. Required.
Mobile Number	`has_twilio = true` OR `ask_phone = true`	Phone input with country code selector. Not required.
Organization Name	`ask_organization_name = true`	Text field. Not required.
Additional Profile Fields	`additional_registration_profile_fields` is non-empty	One field per entry. Each has its own `label`, `type` ("text" or "checkbox"), and `required` flag. Rendered dynamically.
Group Type Dropdowns	`group_types` has entries with joinable groups AND the user is on the standard registration page (not a public view, cohort registration, group registration, or finish-account flow)	One dropdown per group type. Label comes from the group type's `registration_label` (falls back to `name`). Options are the groups within that type. Required.
Learning Path	`learningPathOptions` is non-empty AND the user is on the standard registration page (not a public view, cohort registration, group registration, or finish-account flow)	Dropdown populated from `learningPathOptions`. Pre-selected to `default_lp_id` if set. Disabled if a learning path was pre-selected via URL or context. Required.
Place Selection Prompts	`place_selection_prompts` (dynamic) has entries with groups	Each prompt renders as a separate place-selection step. Prompts only appear if their `location_type_ids` match groups that exist in the database. Required.
SMS Opt-In Checkbox	`has_twilio_premium = true`	Text: "I would like to receive text reminders and updates regarding my learning requirements (Data rates may apply, reply STOP to opt out)". Not required.
Flodesk Opt-In Checkbox	`has_flodesk = true`	Label text comes from `flodesk_opt_in_label`. Not required.
Terms & Conditions Checkbox	`terms_conditions_url` is set (non-null)	Text includes a link to the T&C URL. Required.
Marriage Prep Acknowledgment	The selected learning path's ID is in `marriagePrepIds`	Checkbox acknowledging marriage prep registration. Required when visible.

Preset / Default Values

Field	Config Key	Behavior

Field	Config Key	Behavior
Place dropdown	`default_group_id`	When set, the Place dropdown is pre-selected to this group ID.
Learning Path dropdown	`default_lp_id`	When set, the Learning Path dropdown is pre-selected to this LP ID.
Language dropdown	(browser default)	Always pre-selected to the user's browser language (`navigator.language`), regardless of config.
Email label	`email_label`	When set, replaces the default "Email" label. When null, label is "Email".