Skip to main content
Profile custom fields let your organization store information that is specific to your operating model on Minerva profiles. Administrators define the fields once, and profiles can carry values across every workspace in your organization. Access: Only administrators can configure definitions. In the sidebar, go to Administration > Configuration > Profile Custom Fields. Other users can view and use permitted fields on profiles and in the profiles list. Use this guide when you need to:
  • add organization-specific information such as Loan Number or Loan Status
  • make selected fields available as profile-list columns, filters, and sort options
  • prepare CSV or XLSX files that include custom profile data
  • understand required fields, archival, history, and rollback
  • connect an integration to profile custom fields
Definitions belong to your organization and apply across all its workspaces. Profile values still belong to their profiles. Changing workspaces does not create a second set of definitions.

​
Key concepts

Use field keys, not labels, in API integrations. Labels can change, but keys remain fixed. Record each returned key in the system that sends profile data to Minerva.

​
Configure profile custom fields

The configuration page lists active and archived definitions. It also shows which fields are required, available for filtering, and displayed in the profiles list. To create a field:
  1. Select Create custom field.
  2. Enter a clear label and, when useful, a description.
  3. Confirm the generated field key. Choose a stable key before saving because it cannot be changed later.
  4. Select the field type.
  5. Leave the field optional unless every future profile must contain a value.
  6. Choose whether supported fields can be filtered or shown as a list column.
  7. Set the priority, review the change, and save it.
Choose labels that make sense to reviewers and upload operators. Use Loan Number rather than an internal project code. Descriptions should explain the expected value, not repeat the label.
After you edit or archive a definition, the change may take up to about one minute to appear in profile details, profile lists, and other read views. This delay does not change stored profile values. After the read view refreshes, a renamed label appears under its new name and an archived field is omitted. Profile creates, onboarding, and supplied values in updates validate against the latest definition. If Minerva cannot retrieve that definition, it rejects the write rather than saving an unvalidated value.

​
Supported types

​
Edit Choice options

After you save a Choice field, you can add options, change an option’s display label, and reorder the options. The stored value for each saved option cannot be changed or removed in this release. Minerva hides or disables removal for saved options; you can still remove a newly added row before saving it. Option values identify data already stored on profiles. Preserving those values keeps historical profile data readable when labels or ordering change. Choose durable stored values, and use display labels for wording that may evolve. If the vocabulary must be replaced, contact Minerva Support. You can also archive the field and create a new one, but the new field starts empty and existing profile values are not moved to it. All custom values on one profile have a combined 64 KB limit.
Use Text for identifier-like values, even when they contain only digits. This preserves leading zeroes and avoids numeric limits in downstream tools.

​
Required fields

Optional is the default and is safer during rollout. A required field affects future profile creation:
  • API profile creation and onboarding requests are rejected when the value is missing or null.
  • CSV and XLSX rows fail when the required column or row value is missing or invalid.
  • Existing profiles and values remain unchanged.
  • Unrelated profile updates are not rejected only because an older profile lacks the field.
Coordinate with your technical team before making a field required. Update API integrations, onboarding flows, and upload processes first. A newly required definition is enforced on the next create or import after the change is active.
Administrators can mark up to five non-Structured data fields across the organization as filterable and searchable. A supported definition can also be marked for display in the profiles list. Custom columns appear in the Columns picker after organization fields. Each user’s column selection is saved as an individual preference. Filtering and sorting follow the selected field’s type:
  • Text supports exact and contains searches.
  • Number and Date support exact values and ranges.
  • Yes/No supports either value.
  • Choice supports configured options.
  • Structured data does not support columns, filtering, or sorting.

​
View profile values

When a profile has custom values, Minerva shows the most useful values as chips in the profile header. The complete set appears in the last Profile details tab, ordered by definition priority. Potential matches remains the default tab. Choice fields show their readable option label. Structured data is formatted for review on the profile page. Fields with no stored value are not shown.

​
Include fields in batch uploads

Download a current CSV or XLSX template before preparing a batch. Templates are generated from the active definitions and include the recognized custom field labels in priority order. For each custom column:
  • use the definition label as the header
  • include every required column and a valid value in every imported row
  • use a configured Choice option
  • use YYYY-MM-DD for Date values
  • use valid JSON objects or arrays for Structured data
An invalid required value fails that row. An invalid optional value produces a warning, skips only that custom value, and imports the rest of the profile. Review the validation report before confirming the upload.

​
Connect an API integration

API integrations send an object keyed by immutable field keys and receive a labeled array in profile responses. See the Profile Custom Fields API guide for request formats, response examples, validation rules, and compatibility guidance.

​
Operating model

  1. Define optional fields and confirm labels, types, keys, and Choice options with business and technical owners.
  2. Treat saved Choice option values as immutable identifiers in this release. Use display labels for wording changes, and add options when the vocabulary expands.
  3. Update API producers and batch templates using the active definitions.
  4. Test profile creation, onboarding, updates, reads, filters, and uploads.
  5. Make a field required only after every creation path supplies it.
  6. Review the five-field filterable limit before enabling another field.
  7. Review configuration history after each change.

​
Archive, history, and rollback

Archive a definition when it should no longer accept new values. Archiving prevents new API writes through that key as soon as the change is active and removes the field from active configuration and generated templates. Stored values remain on profile records for history. An archived field may remain visible in profile read views for up to about one minute, then it is omitted after those views refresh. Do not repurpose an old field by changing its label to a different meaning. Archive it and create a new definition with a new key. This keeps historical data understandable. Configuration history records audited changes. Rollback replays the selected historical snapshot through the current configuration checks, so it does not always succeed. In particular, rollback cannot remove a saved Choice option value. A snapshot that predates a later-added option omits that saved value and is rejected with HTTP 409. Use a forward change that keeps every saved Choice value, such as relabeling, reordering, or adding options, or contact Minerva Support. A successful rollback does not reconstruct values that an integration cleared or replace an import file.