User Defined Fields

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query User Defined Field Settings

Retrieve all user-defined field settings configured for the company. User-defined fields allow you to capture custom information about employees that isn't covered by standard fields.

Query Parameters:

This query takes no parameters and returns all user-defined field settings configured for the company.

Response Fields:

Field Description
id Unique identifier for the field setting
name Internal name of the field
order Display order of the field
label User-facing label for the field
tooltip Tooltip text to help users understand the field
placeholder Placeholder text for input fields
dataType Data type (e.g., "checkbox", "text", "number", "date", "select")
fieldLevel Whether the field is "required", "optional", or "hidden"
available Whether the field is currently active

For the complete UserDefinedFieldSetting type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • User-defined fields are configured at the company level
  • The order field determines the sequence in which fields are displayed
  • Data types supported include: checkbox, text, number, date, select, and more
  • Field level controls whether employees must fill in the field during onboarding
  • Only active fields (available: true) are shown to users
  • These settings define the structure; actual values are stored separately per employee

GraphQL Query

query UserDefinedFieldSettings {
  userDefinedFieldSettings {
    id
    name
    order
    label
    tooltip
    placeholder
    dataType
    fieldLevel
    available
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "userDefinedFieldSettings": [
      {
        "id": "416",
        "name": "Has relevant qualifications?",
        "order": 1,
        "label": "Do you have the latest qualification?",
        "tooltip": null,
        "placeholder": null,
        "dataType": "checkbox",
        "fieldLevel": "optional",
        "available": true
      },
      {
        "id": "415",
        "name": "Has drivers license?",
        "order": 2,
        "label": "Do you have a current drivers license?",
        "tooltip": null,
        "placeholder": null,
        "dataType": "checkbox",
        "fieldLevel": "optional",
        "available": true
      }
    ]
  }
}

Query All Employee User Defined Field Responses

Retrieve all employees and their user-defined field responses. This is useful for generating reports or exporting custom employee data.

Query Parameters:

This query takes no parameters and returns all employees with their user-defined field values.

Response Fields:

Field Description
id Employee ID
fullName Employee's full name
userDefinedFields Array of user-defined field values
userDefinedFields[].id Unique identifier for this field value
userDefinedFields[].value The actual value stored
userDefinedFields[].ownerId ID of the owner (employee ID)
userDefinedFields[].ownerType Type of owner (e.g., "employee")
userDefinedFields[].userDefinedFieldSetting The field setting configuration

Implementation Notes:

  • This query returns data for all employees in the company
  • Each employee will have an array of user-defined field values
  • The userDefinedFieldSetting provides context about what the field represents
  • Empty fields may not be included in the response
  • This can be a large response for companies with many employees

GraphQL Query

query EmployeeResponses {
  employees {
    id
    fullName
    userDefinedFields {
      userDefinedFieldSetting {
        id
        name
        order
        label
        tooltip
        placeholder
        dataType
        fieldLevel
        available
      }
      id
      value
      ownerId
      ownerType
    }
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "employees": [
      {
        "id": "72908",
        "fullName": "Craig Bussell",
        "userDefinedFields": [
          {
            "userDefinedFieldSetting": {
              "id": "416",
              "name": "Has relevant qualifications?",
              "order": 1,
              "label": "Do you have the latest qualification?",
              "tooltip": null,
              "placeholder": null,
              "dataType": "checkbox",
              "fieldLevel": "optional",
              "available": true
            },
            "id": "1234",
            "value": "true",
            "ownerId": "72908",
            "ownerType": "employee"
          }
        ]
      }
    ]
  }
}

Query Employee User Defined Field Responses

Retrieve user-defined field responses for a specific employee. This allows you to get custom field data for an individual employee.

Query Parameters:

Parameter Type Required Description
employeeId ID! Yes ID of the employee to query

Response Fields:

Same as "Query All Employee User Defined Field Responses", but filtered to a single employee.

Implementation Notes:

  • This endpoint queries the employee by ID and returns their user-defined field values
  • More efficient than querying all employees when you only need data for one
  • Use this when displaying or updating a specific employee's custom fields
  • The response structure is identical to querying all employees, but with a single result

GraphQL Query

query EmployeeResponses($employeeId: ID!) {
  employee(id: $employeeId) {
    id
    fullName
    userDefinedFields {
      userDefinedFieldSetting {
        id
        name
        order
        label
        tooltip
        placeholder
        dataType
        fieldLevel
        available
      }
      id
      value
      ownerId
      ownerType
    }
  }
}

Example Variables

{
  "employeeId": "72908"
}

Example Response

{
  "data": {
    "employee": {
      "id": "72908",
      "fullName": "Craig Bussell",
      "userDefinedFields": [
        {
          "userDefinedFieldSetting": {
            "id": "416",
            "name": "Has relevant qualifications?",
            "order": 1,
            "label": "Do you have the latest qualification?",
            "tooltip": null,
            "placeholder": null,
            "dataType": "checkbox",
            "fieldLevel": "optional",
            "available": true
          },
          "id": "1234",
          "value": "true",
          "ownerId": "72908",
          "ownerType": "employee"
        }
      ]
    }
  }
}

Add User Defined Field Setting

Create a new user-defined field setting. This defines a new custom field that can be used to collect information from employees.

Mutation Parameters:

Parameter Type Required Description
input AddUserDefinedFieldSettingInput! Yes Input object containing field setting details
input.name String! Yes Internal name for the field
input.order Int! Yes Display order (determines sequence in UI)
input.label String! Yes User-facing label
input.tooltip String No Tooltip text (optional)
input.placeholder String No Placeholder text (optional)
input.dataType String! Yes Data type ("checkbox", "text", "number", "date", etc.)
input.fieldLevel String! Yes Field requirement level ("required", "optional", "hidden")
input.available Boolean! Yes Whether the field is active
input.ownerType String! Yes Owner type (typically "employee")

For the complete input type reference, see AddUserDefinedFieldSettingInput.

Response Fields:

Returns the same fields as the query, confirming the created field setting.

For the complete UserDefinedFieldSetting type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • The name should be unique and descriptive for internal reference
  • The order determines where the field appears relative to other custom fields
  • Common dataType values: "checkbox", "text", "number", "date", "select"
  • Set fieldLevel to "required" to enforce completion during onboarding
  • The ownerType is typically "employee" but could be other entity types in the future
  • Newly created fields are immediately available for use

GraphQL Mutation

mutation AddUserDefinedFieldSetting($input: AddUserDefinedFieldSettingInput!) {
  addUserDefinedFieldSetting(input: $input) {
    id
    name
    order
    label
    tooltip
    placeholder
    dataType
    fieldLevel
    available
  }
}

Example Variables

{
  "input": {
    "name": "First aid certification status",
    "order": 3,
    "label": "Do you have a current first aid certificate?",
    "tooltip": null,
    "placeholder": null,
    "dataType": "checkbox",
    "fieldLevel": "required",
    "available": true,
    "ownerType": "employee"
  }
}

Example Response

{
  "data": {
    "addUserDefinedFieldSetting": {
      "id": "417",
      "name": "First aid certification status",
      "order": 3,
      "label": "Do you have a current first aid certificate?",
      "tooltip": null,
      "placeholder": null,
      "dataType": "checkbox",
      "fieldLevel": "required",
      "available": true
    }
  }
}

Update User Defined Field Setting

Update an existing user-defined field setting. This allows you to modify the configuration of a custom field.

Mutation Parameters:

Parameter Type Required Description
input UpdateUserDefinedFieldSettingInput! Yes Input object containing updated details
input.id ID! Yes ID of the field setting to update
input.name String No Updated internal name
input.order Int No Updated display order
input.label String No Updated user-facing label
input.tooltip String No Updated tooltip text
input.placeholder String No Updated placeholder text
input.dataType String No Updated data type
input.fieldLevel String No Updated field requirement level
input.available Boolean No Updated availability status

For the complete input type reference, see UpdateUserDefinedFieldSettingInput.

Response Fields:

Returns the same fields as the query, with updated values.

For the complete UserDefinedFieldSetting type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • Only provide the fields you want to update; omitted fields retain their current values
  • Changing dataType may affect existing values for this field
  • Setting available to false hides the field from users but preserves existing data
  • Updating fieldLevel to "required" won't retroactively enforce it on existing employees
  • Changes to order will affect the field's position in the UI
  • Existing employee responses are not affected by changes to the setting

GraphQL Mutation

mutation UpdateUserDefinedFieldSetting($input: UpdateUserDefinedFieldSettingInput!) {
  updateUserDefinedFieldSetting(input: $input) {
    id
    name
    order
    label
    tooltip
    placeholder
    dataType
    fieldLevel
    available
  }
}

Example Variables

{
  "input": {
    "id": "417",
    "label": "Do you hold a current first aid certificate?",
    "fieldLevel": "optional"
  }
}

Example Response

{
  "data": {
    "updateUserDefinedFieldSetting": {
      "id": "417",
      "name": "First aid certification status",
      "order": 3,
      "label": "Do you hold a current first aid certificate?",
      "tooltip": null,
      "placeholder": null,
      "dataType": "checkbox",
      "fieldLevel": "optional",
      "available": true
    }
  }
}

Delete User Defined Field Setting

Delete a user-defined field setting. This removes the field configuration from the system.

Mutation Parameters:

Parameter Type Required Description
id ID! Yes ID of the field setting to delete

Response Fields:

Field Description
(boolean) Returns true if the setting was successfully deleted

Implementation Notes:

  • Deleting a field setting will also delete all associated employee values
  • This operation cannot be undone - proceed with caution
  • Consider setting available to false instead if you want to preserve existing data
  • The deletion is immediate and affects all employees
  • Any integrations relying on this field will need to be updated

GraphQL Mutation

mutation DeleteUserDefinedFieldSetting($id: ID!) {
  deleteUserDefinedFieldSetting(id: $id)
}

Example Variables

{
  "id": "417"
}

Example Response

{
  "data": {
    "deleteUserDefinedFieldSetting": true
  }
}

Add User Defined Field Value

Add a value for a user-defined field for a specific employee. This stores the employee's response to a custom field.

Mutation Parameters:

Parameter Type Required Description
input AddUserDefinedFieldInput! Yes Input object containing field value
input.value String! Yes The value to store
input.userDefinedFieldSettingId String! Yes ID of the field setting
input.ownerType String! Yes Owner type (typically "employee")
input.ownerId String! Yes ID of the owner (employee ID)

For the complete input type reference, see AddUserDefinedFieldInput.

Response Fields:

Field Description
value The stored value
ownerId ID of the owner
ownerType Type of owner

For the complete UserDefinedField type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • The value is stored as a string regardless of the field's data type
  • For checkbox fields, use "true" or "false" as strings
  • For date fields, use ISO date format
  • The userDefinedFieldSettingId must reference an existing field setting
  • The ownerId must be a valid employee ID
  • If a value already exists for this combination, use the update mutation instead

GraphQL Mutation

mutation AddUserDefinedFieldValue($input: AddUserDefinedFieldInput!) {
  addUserDefinedField(input: $input) {
    value
    ownerId
    ownerType
  }
}

Example Variables

{
  "input": {
    "value": "true",
    "userDefinedFieldSettingId": "417",
    "ownerType": "employee",
    "ownerId": "72909"
  }
}

Example Response

{
  "data": {
    "addUserDefinedField": {
      "value": "true",
      "ownerId": "72909",
      "ownerType": "employee"
    }
  }
}

Update User Defined Field Value

Update an existing user-defined field value for an employee. This modifies the employee's response to a custom field.

Mutation Parameters:

Parameter Type Required Description
input UpdateUserDefinedFieldInput! Yes Input object containing updated value
input.id ID! Yes ID of the field value to update
input.value String! Yes The new value to store

For the complete input type reference, see UpdateUserDefinedFieldInput.

Response Fields:

Field Description
id Unique identifier for the value
value The updated value
ownerId ID of the owner
ownerType Type of owner

For the complete UserDefinedField type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

  • The id parameter refers to the user-defined field value record, not the setting
  • The value is stored as a string regardless of the field's data type
  • You can obtain the value ID from the query endpoints
  • Only the value can be updated; to change other attributes, delete and recreate
  • Updates are immediate and reflected in all relevant queries

GraphQL Mutation

mutation UpdateUserDefinedFieldValue($input: UpdateUserDefinedFieldInput!) {
  updateUserDefinedField(input: $input) {
    id
    value
    ownerId
    ownerType
  }
}

Example Variables

{
  "input": {
    "id": "1234",
    "value": "false"
  }
}

Example Response

{
  "data": {
    "updateUserDefinedField": {
      "id": "1234",
      "value": "false",
      "ownerId": "72909",
      "ownerType": "employee"
    }
  }
}