Custom Fields API

Overview

Custom fields allow you to extend Blue’s standard record structure with additional data fields specific to your business needs. They provide a powerful way to capture structured data beyond the built-in fields like title, description, and due date.

Custom fields are defined at the workspace level and can be used across all records (todos) within that workspace. Each field has a specific type that determines its validation rules, input format, and display behavior.

Available Operations

Core Field Management

Field Values

Custom Field Types

Text Fields

Selection Fields

Numeric Fields

Contact Fields

Date and Time Fields

Location and Geography

File and Media

System Fields

Interactive Fields

Key Concepts

Field Definition

• Custom fields are defined at the workspace level
• Each field has a unique name and type
• Fields can include validation rules and constraints
• Configuration options vary by field type

Field Values

• Values are stored on individual records (todos)
• Each record can have different values for the same field
• Empty/null values are allowed for optional fields
• Values are validated according to field type rules

Permissions Model

Custom fields respect workspace-level permissions:

*Edit Fields refers to modifying field settings (name, type, options, validation rules) - not setting field values on records

Custom Role Permissions

• Workspaces can have custom roles with field-specific permissions
• Fields can be marked as editable/non-editable per role
• Custom roles can restrict access to specific fields

Common Patterns

Creating a Basic Custom Field

mutation CreateCustomField {
  createCustomField(input: {
    name: "Priority Level"
    type: SELECT_SINGLE
    description: "Task priority level"
    customFieldOptions: [
      { title: "Low", color: "#28a745" }
      { title: "Medium", color: "#ffc107" }
      { title: "High", color: "#fd7e14" }
      { title: "Critical", color: "#dc3545" }
    ]
  }) {
    id
    name
    type
    customFieldOptions {
      id
      title
      color
    }
  }
}

Setting Field Values on Records

mutation SetFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"  # For SELECT_SINGLE
  })
}

Querying Records with Custom Fields

query GetTodosWithCustomFields {
  todos(projectId: "project_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      # Type-specific value fields
      text           # TEXT_SINGLE, TEXT_MULTI, EMAIL, etc.
      number         # NUMBER, CURRENCY, PERCENT, RATING
      selectedOption # SELECT_SINGLE
      selectedOptions # SELECT_MULTI
      checked        # CHECKBOX
      date           # DATE
    }
  }
}

Creating Records with Custom Field Values

mutation CreateTodoWithCustomFields {
  createTodo(input: {
    title: "New task"
    todoListId: "list_123"
    customFields: [
      { customFieldId: "priority_field", value: "high_priority_option" }
      { customFieldId: "budget_field", value: "5000" }
      { customFieldId: "notes_field", value: "Additional context here" }
    ]
  }) {
    id
    title
    customFields {
      customField { name }
      value
    }
  }
}

Best Practices

Field Design

1. Use descriptive names - Make field purposes clear
2. Choose appropriate types - Match field type to data requirements
3. Set validation rules - Use min/max values, required fields
4. Organize logically - Group related fields together

Performance Considerations

1. Limit field count - Too many fields can impact performance
2. Use pagination - When querying large datasets
3. Index key fields - For fields used in filtering/sorting
4. Avoid deep nesting - Keep field relationships simple

Data Quality

1. Validate input - Use appropriate field types with validation
2. Provide defaults - Set sensible default values where appropriate
3. Use consistent formats - Standardize data entry patterns
4. Regular cleanup - Remove unused fields and options

User Experience

1. Clear descriptions - Provide helpful field descriptions
2. Logical ordering - Position fields in natural workflow order
3. Visual hierarchy - Use colors and formatting effectively
4. Progressive disclosure - Show fields when relevant

Error Handling

Common errors when working with custom fields:

Related Resources

• Records API - Working with records that contain custom fields
• Workspaces API - Managing workspaces that contain custom fields
• Automations API - Automating workflows with custom field triggers
• User Management API - Managing custom field permissions