iCIMS Custom Fields Setup: A Consultant’s Complete Guide

If you have ever had to “just add one more field” in iCIMS and then watched a workflow rule break, a merge tag come up blank, or a Workday integration silently drop the value, you are in the right place. iCIMS custom fields setup looks deceptively simple. You add a field on a profile, save it, and move on. But the decisions you make in those first five clicks ripple into reporting, integrations, candidate experience, and audit trails for years.

This guide is the consultant version of the conversation we have at the start of nearly every iCIMS implementation and audit. We will cover where custom fields live, the field types iCIMS supports, which profile to put them on, how permissions work, what happens when you promote them from sandbox to production, and the five mistakes that quietly cause the most damage. Our goal: by the end of this post, you will configure your next custom field with the same care a seasoned iCIMS admin would.

Why iCIMS custom fields setup feels harder than it should

Here’s the thing about iCIMS. Out of the box, it ships with a vendor template that almost never matches how your team actually hires. So the moment you decide to track a real piece of data, say a hiring manager’s preferred start date, a candidate’s required clearance level, or a referral payout amount, you reach for a custom field. Easy enough.

The trouble starts when you realize iCIMS has five different profile types you could put that field on, ten different field types you could use, a permissions model that runs through login groups, an internal field ID system that does not match the label you see on screen, and a sandbox-to-production promotion process that will quietly assign your field a brand new ID. None of that is documented in one place inside the platform. New admins discover most of it after something breaks.

That gap between “add a field” and “do it right” is exactly where most iCIMS instances drift over time. We see it on every audit. The platform is fine. The setup decisions made years ago, by people who are no longer at the company, are what hurt.

Where iCIMS custom fields actually live in the system

Custom fields are configured under Admin > System Configuration > System, then you select the Profile Type you want to edit. Each Profile Type has its own Platform menu where Tabs, Sections, and Fields are defined. The pattern is the same across all Profile Types, which makes the model easy to learn once.

If you have never poked around in here before, you will see something like this hierarchy on the Person profile:

• Profile (Person)
  • Tab (e.g., Overview)
    • Section (e.g., Contact Information)
      • Fields (First Name, Last Name, custom field 1234, etc.)

You cannot drop a field straight onto a tab. The Section is required as the container. That sounds picky but it matters: Sections control visual grouping, collapsible behavior, and in some cases conditional display. Think of Sections as the way you tell a recruiter “these fields belong together.”

For more on how Profile Types relate to each other and why this matters, the iCIMS data structure explainer for non-technical teams is the companion piece for this section.

The 10 field types iCIMS gives you, and when to use each

iCIMS supports ten field types. Picking the right one at the start saves you from re-doing everything later, because most field types cannot be converted in-place. If you build a Text field and later wish it were a Dropdown, you have to create a new field and migrate the data.

Here is the practical guide for each one.

Person, Job, Recruiting Workflow, or Talent Pool: pick the right profile

This is the decision that causes the most rework. iCIMS has multiple Profile Types, and a custom field on the wrong Profile is technically functional but operationally awful.

Here is the short version, with the test we use on every client engagement.

The test: ask yourself, “If this candidate applies to a second job, should the value carry over?” If yes, it is a Person field. If no, it is a Recruiting Workflow field. If it is about the job and would be identical for every applicant on it, it is a Job field.

For more on how these Profile Types interlock, especially around Workflow Profiles and which fields show where, the guide to iCIMS workflow rules that won’t trigger walks through how field placement affects workflow execution.

Custom dropdowns: the single best decision for reporting

If you only take one habit from this post, take this one: any field you ever want on a dashboard, in a report, or as a filter in a saved search, must be a Dropdown. Not Text. Not Textarea. Dropdown.

Here’s why. Reports in iCIMS work by grouping on a field’s value. Free text never groups cleanly. Even with perfect data discipline, you will see “Engineering” and “engineering” treated as different values. Dropdowns force a single canonical value per option, which means your reports actually aggregate.

When you configure a Dropdown, you choose:

• Single-select vs Multi-select. Use multi-select sparingly. Reports on multi-select fields require careful filter logic and can double-count.
• The dropdown list (option set). You can either create a list scoped to this field, or reuse a shared list. Reuse shared lists wherever possible. Three fields with “Department” should all pull from the same list so reporting is consistent across them.
• Default value. If most candidates are one value, set the default and reduce manual entry. Just remember the default will fire on every new record, so do not default to a value that requires deliberate choice (like “Department”).
• Required. Make a field required only when you are certain every legacy record either has the value or can tolerate being edited. Required on a brand-new field is fine. Required on a field you are converting from Text is dangerous.

Field-level permissions and login groups

iCIMS uses login groups to control access. A login group is a permission bundle that decides what a user can see and do. Field-level permissions plug into that model: for each custom field, you can grant or deny read and edit on a per-login-group basis.

This matters most for sensitive data. Salary fields, compensation history, veteran status, disability self-identification, internal scoring, and EEO categories should all have explicit field-level permissions. Default behavior in iCIMS is fairly open inside an instance, so “I added the field, surely only the right people can see it” is wrong. If you did not explicitly restrict the field, anyone with profile access can read it.

The pattern we use on every client engagement looks like this:

1. Create the field with default permissions.
2. Identify the login groups that need read access. Identify the (smaller) subset that need edit access.
3. Set field-level permissions explicitly for every login group, even the ones that should have no access. Explicit is auditable. Implicit is not.
4. Document the decision somewhere outside iCIMS. When the field is eventually questioned in an audit (and it will be), you want to know why you made that choice.

If the login group structure feels unclear, the consultant’s guide to iCIMS login groups setup is the field’s mirror image. The two configurations work together. You cannot do field-level permissions well without a clean login group structure underneath.

Sandbox to production: the field ID drift problem

Every custom field in iCIMS has an internal numeric ID in the format field1234. This ID is invisible in the normal UI but is what merge tags, the REST API, iForms, and HRIS integration mappings actually reference under the hood.

Here is the gotcha. If you build a field in your sandbox environment with internal ID field5678, and then manually rebuild that same field in production, iCIMS will assign it a brand new ID, say field9012. The label is identical. The behavior in the UI is identical. But every merge tag, every integration field map, and every saved search that referenced field5678 needs to be re-pointed at field9012 in production. Skip that step and integrations silently fail, emails go out with blank merge variables, and iForms render empty placeholders.

How to handle it well:

1. Keep a field inventory spreadsheet. For every custom field, log: label, profile type, field type, sandbox ID, production ID (filled in after promotion), where it is referenced (templates, iForms, integrations, saved searches).
2. On promotion day, recreate fields in a single change window, capture the new production IDs, then immediately update every dependent artifact.
3. Smoke-test merge tags, iForms, and integration runs on production records before declaring done.
4. For complex implementations, ask iCIMS Professional Services about configuration migration tooling. Some configurations can be promoted between environments with the IDs preserved. Get the answer in writing before assuming.

Merge variables, iForms, and HRIS integrations

The downstream impact of a custom field is where the real cost lives. A field on its own is just storage. The moment you reference it from another part of the system, you create a dependency.

Merge variables in email templates and offer letters

Custom fields show up as merge tags in email templates, offer letter templates, and iCIMS Onboard documents. The merge tag references the field by internal ID. If the field is empty for that record, the tag renders blank. If the field type does not match the destination’s expected format (e.g., a Datetime in a template that formats as Dateonly), you may see odd outputs.

Our rule of thumb: if you put a custom field into a merge tag, also configure it as required (or with a sensible default) at the right point in the workflow. Otherwise, the moment a recruiter forgets to populate it, the candidate receives an email with a glaring blank.

iForms (electronic forms)

iForms can render and capture custom field values. Field type matters: a Dropdown becomes a dropdown on the form, Dateonly becomes a date picker, Number becomes a number input with validation. For multi-step iForms or compliance forms (W-4, I-9), small choices like making a field Dropdown instead of Text dramatically improve completion accuracy. The companion guide on iCIMS iForms setup and custom form configuration covers form-side decisions in depth.

HRIS integrations: Workday, UKG, ADP

This is where field choices become expensive. Every HRIS integration mapping references custom fields by internal ID. When you add a field to iCIMS that you intend to flow into Workday, UKG Pro, or ADP Workforce Now, you also have to:

• Decide which profile it lives on (typically Job for requisition data, Person or Onboarding for new hire data).
• Add it to the integration field map on both ends.
• Validate format compatibility. Dropdown values in iCIMS must map cleanly to picklist values in the HRIS. Mismatched values silently drop on sync.
• Re-test the integration after every field change. Even a label edit can break a tightly-mapped sync.

The honest answer: do not add a field that crosses the integration boundary without a 30-minute conversation between TA Ops and HRIS Ops. We see more sync drift caused by uncoordinated field additions than by any other root cause.

The 5 most common iCIMS custom fields setup mistakes

Here are the patterns we see on nearly every iCIMS audit, with the fixes that save the most time.

For teams already mid-implementation or staring at a tangled instance, an iCIMS implementation consultant can help triage and prioritize the fixes. For ongoing care, our iCIMS managed services team takes on the field inventory and audit cycle so it does not fall back to a single overloaded admin.

Frequently asked questions