Sign Up
Contact Log In Sign Up
System Status

Complete API reference for managing custom fields in Blue - create, configure, and use custom fields to extend your data structure

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 project level and can be used across all records (todos) within that project. Each field has a specific type that determines its validation rules, input format, and display behavior.

Available Operations

Core Field Management

Operation Description Link
List Custom Fields Query and filter custom fields View Details →
Create Custom Field Add new custom fields to projects View Details →
Delete Custom Field Remove custom fields with proper cleanup View Details →

Field Values

Operation Description Link
Set Field Values Set and update custom field values on records View Details →

Custom Field Types

Text Fields

Type Description Use Cases Link
TEXT_SINGLE Single line text input Names, titles, short descriptions View Details →
TEXT_MULTI Multi-line text area Long descriptions, notes, comments View Details →

Selection Fields

Type Description Use Cases Link
SELECT_SINGLE Single selection dropdown Status, priority, category View Details →
SELECT_MULTI Multiple selection dropdown Tags, skills, categories View Details →
CHECKBOX Boolean checkbox field Flags, approvals, confirmations View Details →

Numeric Fields

Type Description Use Cases Link
NUMBER Numeric input Quantities, scores, measurements View Details →
CURRENCY Currency amount Budgets, costs, pricing View Details →
PERCENT Percentage value Completion rates, discounts View Details →
RATING Star rating with custom scale Performance ratings, satisfaction View Details →
FORMULA Calculated field based on other fields Totals, computations, aggregations View Details →

Contact Fields

Type Description Use Cases Link
EMAIL Email address with validation Contact information, notifications View Details →
PHONE Phone number with international formatting Contact details, emergency contacts View Details →
URL Web URL with validation Links, references, resources View Details →

Date and Time Fields

Type Description Use Cases Link
DATE Date picker Deadlines, milestones, events View Details →
TIME_DURATION Time tracking field Work hours, duration estimates View Details →

Location and Geography

Type Description Use Cases Link
LOCATION Geographic location (lat/lng) Addresses, venues, service areas View Details →
COUNTRY Country selector Regional assignments, localization View Details →

File and Media

Type Description Use Cases Link
FILE File attachment Documents, images, resources View Details →

System Fields

Type Description Use Cases Link
UNIQUE_ID Auto-generated unique identifier Ticket numbers, order IDs View Details →
REFERENCE Link to records in another project Cross-project relationships View Details →
LOOKUP Pull data from referenced records Aggregate data from related records View Details →

Interactive Fields

Type Description Use Cases Link
BUTTON Actionable button field Triggers, actions, workflows View Details →
CURRENCY_CONVERSION Currency conversion field Multi-currency calculations View Details →

Key Concepts

Field Definition

  • Custom fields are defined at the project 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 project-level permissions:

Role Create Fields Edit Fields* Set Values View Values
OWNER ✅ Yes ✅ Yes ✅ Yes ✅ Yes
ADMIN ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MEMBER ❌ No ❌ No ✅ Yes ✅ Yes
CLIENT ❌ No ❌ No ✅ Limited ✅ Limited

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

Custom Role Permissions

  • Projects 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:

Error Code Description Solution
CUSTOM_FIELD_NOT_FOUND Field doesn't exist Verify field ID and project access
VALIDATION_ERROR Value doesn't match field type Check format and validation rules
UNAUTHORIZED Insufficient permissions Ensure proper role level
CUSTOM_FIELD_VALUE_PARSE_ERROR Invalid value format Review field type requirements
© Blue | Designed with ❤ across the

AI Assistant

Responses are generated using AI and may contain mistakes.

How can I help you?

Ask me anything about Blue or this documentation.

Enter to send • Shift+Enter for new line • ⌘I to open