Custom Data Fields Impact on Employee Data

The type of data field chosen and where it is built has a direct impact on the structure of employee data and therefore integrations. It is important to have a thorough understanding of how the choices made when creating the data impact the structure of employee data - often called employee shape or candidate shape.

JSON Overview

Employee data is stored as JSON (JavaScript Object Notation). This is a simple way of organizing and storing data so that it's easy for systems to read, use, and pass along to other systems. It is a structured and labeled format. It is similar to a filled-out form in appearance. 

Every piece of employee data is stored as a label (the reference name) paired with a value (the actual data). For example:

{
  "id": "abc123",
  "dateOfBirth": "1990-12-31",
  "startDate": "2024-03-14"
}

In the above example:

• "startDate" is the field. This is the container we are creating when we make Data Fields. It tells you what the data represents.
• "2024-03-14" is the value. This is what employees or Team Members are entering when completing forms. It's the actual data stored in that field

JSON allows each piece of employee information to be individually labeled and organized, which means:

• Data can be grouped logically (e.g., all address info together, all phone info together)
• Systems can find and use a specific piece of data (like "startDate") without confusion
• The same underlying data field can be displayed differently depending on where it's used but its structure in the employee shape stays consistent. This allows for extreme flexibility in customizing forms

With JSON data can be nested. This means a field can contain a group of other fields, not just a single value. For example:

{
  "name": {
    "first": "John",
    "last": "Doe"
  }
}

Here, "name" isn't a single value. It's a container holding multiple related fields.

This is the kind of structural difference that changes depending on where and how a field is created.

Employee Data in JSON

Below is a sample of how a single employee's record is structured in JSON.

{
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "email": {
    "address": "[e-mail]"
  },
  "startDate": "2026-06-24",
  "ssn": "123456789",
  "dateOfBirth": "1990-12-31",
  "addresses": {
    "home": {
      "streetLine1": "123 Main Street",
      "city": "Minneapolis",
      "regionCode": "MN",
      "postalCode": "55401",
      "countryCode": "US"
    }
  },
  "customFields": {
    "physicalLocation": "St. Paul Office",
    "benefitDate": "2026-10-01",
    "officePhone": "4101230000",
    "workEquipment": {
      "idealWorkspace": "Office",
      "laptopType": "Macbook",
      "numberOfMonitors": "Single Monitor",
      "phoneType": "iPhone"
    },
    "emergencyContact": [
      {
        "firstName": "Jane",
        "relation": "Wife",
        "phone": "4105551234"
      },
      {
        "firstName": "Sam",
        "relation": "Friend",
        "phone": "4100009876"
      }
    ]
  },
  "id": "abc123",
  "createdOn": "2026-06-24T20:49:00Z",
  "updatedOn": "2026-07-20T21:06:37Z",
  "userInfo": {
    "UserApiIdentifier": "xxxxx1111111zzzzzzz",
    "IsTest": false,
    "TimeZone": "(UTC-06:00) Central Time (US & Canada)",
    "TimeZoneCode": "UTC-06:00",
    "Active": true
  }
}

To view the Employee shape of an actual employee you can view the data on the employee's profile or call the Candidate/{id}-GET.  Documentation around Click Boarding's APIs can be found here: http://developer.clickboarding.com.

Fields at the root level

Fields like startDate, dateOfBirth, and addresses sit at the root level of the record. These aren't nested inside another section. Root-level fields are typically built-in, system-defined fields.

While it is technically possible to build new fields at the root level, this isn't recommended. Any new data fields your organization needs should instead be added to the customFields section. Keeping custom fields contained in one place keeps the record organized, predictable, and easier to maintain as your data needs grow.

If you selected Create Data Field after first selecting the Data Fields menu item, the field would be created at the root level.

The customFields section

This is where organization-specific data lives. In this example, several different kinds of custom fields are represented:

• physicalLocation - a text field, storing a text value ("St. Paul Office")
• benefitDate - a date field, storing a date value in a standardized format
• officePhone - a phone field, storing a phone number
• workEquipment - a data field group. A data field group bundles several related fields together. In our example, one set of equipment preferences (idealWorkspace, laptopType, numberOfMonitors, phoneType) tied to this employee.
• emergencyContact - a collection. Unlike a data field group, a collection is built to hold multiple instances of the same kind of information. Here, the employee has two emergency contacts that each have their own firstName, relation, and phone. A collection can expand to include as many entries as needed, which is what distinguishes it structurally from a field group.

In the Admin UI, when you select Custom Fields and add a data field, this is where it is being added. You can denote that you are no longer on the root level by the presence of the name of the group at the top as well as the general section. This includes the reference path which shows you how where the field is in relation to the root level. In the below image we are in root -> customFields

Why This Matters

The structural choices made when building a data field doesn't only impact how data looks internally but also determines how that data can be consumed, mapped, and relied upon by integrations and other systems.

There are two main take aways:

1. Location determines where integrations look for data. An integration built to pull physicalLocation will look for it at customFields.physicalLocation. If that field were instead built at the root level, the integration would need a different path (physicalLocation with no prefix). Inconsistent placement across data fields can lead to additional effort and complexity with integrations
2. Type affects the shape of data an integration receives, not just its value. A few examples:
   • A text data field (like officePhone) always returns a single, simple value. An integration can map it directly to one field on the other end.
   • A data field group (like workEquipment) always returns one object with a set of sub-fields. An integration can safely assume that structure will always be present in that same shape.
   • A collection (like emergencyContact) returns an array which could have one entry or have many. An integration must be built to handle this variety. If an integration is instead built assuming there will always be exactly one emergency contact, it will break the moment an employee has two. 

Finally, Collections cannot be used as custom filters on dashboards because they do not map cleanly to a single value per employee.