Guides
Start typing to search…

Custom Fields

Custom fields allow you to attach additional structured data to shifts. Field definitions are created in the Connecteam UI, and values can be set and updated via the API.

Overview

Custom fields enable you to track shift-specific information such as:

  • Project codes
  • Cost centers
  • Client names
  • Equipment IDs
  • Any other metadata relevant to your business

How It Works

1. Define Fields (UI Only)

Custom field definitions must be created in the Connecteam UI:

  1. Navigate to your Scheduler settings
  2. Go to Custom Fields section
  3. Create fields with types like text, number, dropdown, etc.

2. Get Field Definitions (API)

Retrieve available custom fields using the API:

curl --request GET \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/custom-fields/shifts \
  --header 'X-API-KEY: YOUR_API_KEY'

3. Set Values (API)

When creating or updating shifts, include custom field values:

{
  "customFields": [
    {
      "id": "field_abc123",
      "value": "PROJ-2024-001"
    }
  ]
}

API Endpoint

Get Custom Field Definitions

Endpoint:

GET /scheduler/v1/schedulers/{schedulerId}/custom-fields/shifts

Response:

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "customFields": [
      {
        "id": "field_abc123",
        "title": "Project Code",
        "type": "text",
        "required": false,
        "order": 1
      },
      {
        "id": "field_def456",
        "title": "Cost Center",
        "type": "dropdown",
        "required": true,
        "options": [
          {"id": "opt1", "label": "Operations"},
          {"id": "opt2", "label": "Sales"}
        ],
        "order": 2
      }
    ]
  },
  "paging": {
    "offset": 1
  }
}

Working with Custom Fields

Creating Shifts with Custom Fields

Include custom field values in the shift creation request:

curl --request POST \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "startTime": 1736924400,
      "endTime": 1736953200,
      "title": "Project Shift",
      "isPublished": true,
      "assignedUserIds": [9170357],
      "customFields": [
        {
          "id": "field_abc123",
          "value": "PROJ-2024-001"
        },
        {
          "id": "field_def456",
          "value": "CC-Operations"
        }
      ]
    }
  ]'
📝

Note

See Creating Shifts for full details on shift creation.

Getting Shifts with Custom Fields

Custom fields are automatically included in shift responses:

curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/6784dacb3c07733b0a849f49' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response:

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "6784dacb3c07733b0a849f49",
    "title": "Project Shift",
    "startTime": 1736924400,
    "endTime": 1736953200,
    "customFields": [
      {
        "id": "field_abc123",
        "title": "Project Code",
        "value": "PROJ-2024-001"
      },
      {
        "id": "field_def456",
        "title": "Cost Center",
        "value": "CC-Operations"
      }
    ]
  }
}
📝

Note

See Getting Shifts for full query and filtering options.

Updating Custom Field Values

Update custom field values on existing shifts:

curl --request PUT \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "shiftId": "6784dacb3c07733b0a849f49",
      "customFields": [
        {
          "id": "field_abc123",
          "value": "PROJ-2024-002"
        }
      ]
    }
  ]'
💡

Partial Updates

You only need to include the fields you want to change. Other custom field values remain unchanged.

📝

Note

See Updating Shifts for full update capabilities.

Custom Field Types

The following field types are supported (configured in UI):

TypeDescriptionValue Format
TextSingle-line text inputString
NumberNumeric inputNumber or string
DropdownSingle selection from optionsOption ID (string)
Multi-selectMultiple selectionsArray of option IDs
DateDate pickerISO 8601 date string
CheckboxBoolean toggleBoolean

Best Practices

1. Retrieve Definitions First

Always fetch custom field definitions before setting values:

// 1. Get available custom fields
const fields = await getCustomFields(schedulerId);

// 2. Find the field you need
const projectCodeField = fields.find(f => f.title === 'Project Code');

// 3. Set the value
const shift = {
  title: 'Morning Shift',
  startTime: 1736924400,
  endTime: 1736953200,
  customFields: [
    { id: projectCodeField.id, value: 'PROJ-001' }
  ]
};

2. Handle Required Fields

Respect the required flag when creating shifts:

const requiredFields = fields.filter(f => f.required);

// Ensure all required fields have values
const customFields = requiredFields.map(field => ({
  id: field.id,
  value: getValueForField(field)
}));

3. Validate Dropdown Options

For dropdown fields, ensure values match available options:

const costCenterField = fields.find(f => f.title === 'Cost Center');
const validOption = costCenterField.options.find(opt => opt.label === 'Sales');

customFields.push({
  id: costCenterField.id,
  value: validOption.id  // Use option ID, not label
});

4. Batch Operations

When creating multiple shifts with the same custom fields:

curl --request POST \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '[
    {
      "startTime": 1736924400,
      "endTime": 1736953200,
      "title": "Shift 1",
      "assignedUserIds": [9170357],
      "customFields": [{"id": "field_abc123", "value": "PROJ-001"}]
    },
    {
      "startTime": 1736953200,
      "endTime": 1736982000,
      "title": "Shift 2",
      "assignedUserIds": [9170358],
      "customFields": [{"id": "field_abc123", "value": "PROJ-001"}]
    }
  ]'

Common Use Cases

Project Tracking

Track which project each shift belongs to:

{
  "customFields": [
    {"id": "field_project", "value": "PROJ-2024-001"},
    {"id": "field_phase", "value": "Construction"}
  ]
}

Cost Center Allocation

Assign shifts to specific cost centers for accounting:

{
  "customFields": [
    {"id": "field_cost_center", "value": "CC-Operations"},
    {"id": "field_budget_code", "value": "BG-2024-Q1"}
  ]
}

Client Assignment

Track which client a shift is for:

{
  "customFields": [
    {"id": "field_client", "value": "Acme Corp"},
    {"id": "field_site", "value": "Downtown Office"}
  ]
}

Equipment Tracking

Record equipment needed for shifts:

{
  "customFields": [
    {"id": "field_vehicle", "value": "VAN-042"},
    {"id": "field_tools", "value": ["tool_drill", "tool_saw"]}
  ]
}

Error Handling

Invalid Field ID

{
  "detail": "Custom field with id 'invalid_field' does not exist"
}

Solution: Fetch current field definitions and use valid IDs.

Missing Required Field

{
  "detail": "Required custom field 'Cost Center' is missing"
}

Solution: Include all fields marked as required: true.

Invalid Dropdown Value

{
  "detail": "Invalid option 'invalid_opt' for field 'Department'"
}

Solution: Use option IDs from the field definition.

Related Pages

API Reference

Updated 7 days ago