--- updatedAt: 2026-02-01T11:19:39.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # 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: ```bash 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: ```json { "customFields": [ { "id": "field_abc123", "value": "PROJ-2024-001" } ] } ``` *** ## API Endpoint ### Get Custom Field Definitions **Endpoint:** ``` GET /scheduler/v1/schedulers/{schedulerId}/custom-fields/shifts ``` **Response:** ```json { "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: ```bash 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](scheduler-create-shifts) for full details on shift creation. ### Getting Shifts with Custom Fields Custom fields are automatically included in shift responses: ```bash curl --request GET \ --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/6784dacb3c07733b0a849f49' \ --header 'X-API-KEY: YOUR_API_KEY' ``` **Response:** ```json { "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](scheduler-get-shifts) for full query and filtering options. ### Updating Custom Field Values Update custom field values on existing shifts: ```bash 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](scheduler-update-shifts) for full update capabilities. *** ## Custom Field Types The following field types are supported (configured in UI): | Type | Description | Value Format | | :--------------- | :---------------------------- | :------------------- | | **Text** | Single-line text input | String | | **Number** | Numeric input | Number or string | | **Dropdown** | Single selection from options | Option ID (string) | | **Multi-select** | Multiple selections | Array of option IDs | | **Date** | Date picker | ISO 8601 date string | | **Checkbox** | Boolean toggle | Boolean | *** ## Best Practices ### 1. Retrieve Definitions First Always fetch custom field definitions before setting values: ```javascript // 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: ```javascript 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: ```javascript 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: ```bash 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: ```json { "customFields": [ {"id": "field_project", "value": "PROJ-2024-001"}, {"id": "field_phase", "value": "Construction"} ] } ``` ### Cost Center Allocation Assign shifts to specific cost centers for accounting: ```json { "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: ```json { "customFields": [ {"id": "field_client", "value": "Acme Corp"}, {"id": "field_site", "value": "Downtown Office"} ] } ``` ### Equipment Tracking Record equipment needed for shifts: ```json { "customFields": [ {"id": "field_vehicle", "value": "VAN-042"}, {"id": "field_tools", "value": ["tool_drill", "tool_saw"]} ] } ``` *** ## Error Handling ### Invalid Field ID ```json { "detail": "Custom field with id 'invalid_field' does not exist" } ``` **Solution:** Fetch current field definitions and use valid IDs. ### Missing Required Field ```json { "detail": "Required custom field 'Cost Center' is missing" } ``` **Solution:** Include all fields marked as `required: true`. ### Invalid Dropdown Value ```json { "detail": "Invalid option 'invalid_opt' for field 'Department'" } ``` **Solution:** Use option IDs from the field definition. *** ## Related Pages * [Getting Shifts](scheduler-get-shifts) - Query shifts with custom fields * [Creating Shifts](scheduler-create-shifts) - Create shifts with custom field values * [Updating Shifts](scheduler-update-shifts) - Update custom field values * [Shifts Overview](scheduler-shifts) - Complete guide to shifts *** [API Reference](https://developer.connecteam.com/reference/get-shift-custom-fields)