Checkbox Custom Field

Checkbox custom fields provide a simple boolean (true/false) input for tasks. They’re perfect for binary choices, status indicators, or tracking whether something has been completed.

Basic Example

Create a simple checkbox field:

mutation CreateCheckboxField {
  createCustomField(input: {
    name: "Reviewed"
    type: CHECKBOX
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a checkbox field with description and validation:

mutation CreateDetailedCheckbox {
  createCustomField(input: {
    name: "Customer Approved"
    type: CHECKBOX
    description: "Check this box when the customer has approved the work"
  }) {
    id
    name
    type
    description
  }
}

Input Parameters

CreateCustomFieldInput

Setting Checkbox Values

To set or update a checkbox value on a task:

mutation CheckTheBox {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    checked: true
  })
}

To uncheck a checkbox:

mutation UncheckTheBox {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    checked: false
  })
}

SetTodoCustomFieldInput Parameters

Creating Tasks with Checkbox Values

When creating a new task with checkbox values:

mutation CreateTaskWithCheckbox {
  createTodo(input: {
    title: "Review contract"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "checkbox_field_id"
      value: "true"  # Pass as string
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      checked
    }
  }
}

Accepted String Values

When creating tasks, checkbox values must be passed as strings:

Note: String comparisons during task creation are case-sensitive. The values must exactly match "true", "1", or "checked" to result in a checked state.

Response Fields

TodoCustomField Response

Automation Integration

Checkbox fields trigger different automation events based on state changes:

This allows you to create automations that respond to checkbox state changes, such as:

• Sending notifications when items are approved
• Moving tasks when review checkboxes are checked
• Updating related fields based on checkbox states

Data Import/Export

Importing Checkbox Values

When importing data via CSV or other formats:

• "true", "yes" → Checked (case-insensitive)
• Any other value (including "false", "no", "0", empty) → Unchecked

Exporting Checkbox Values

When exporting data:

• Checked boxes export as "X"
• Unchecked boxes export as empty string ""

Required Permissions

Error Responses

Invalid Value Type

{
  "errors": [{
    "message": "Invalid value type for checkbox field",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Field Not Found

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Best Practices

Naming Conventions

• Use clear, action-oriented names: “Approved”, “Reviewed”, “Is Complete”
• Avoid negative names that confuse users: prefer “Is Active” over “Is Inactive”
• Be specific about what the checkbox represents

When to Use Checkboxes

• Binary choices: Yes/No, True/False, Done/Not Done
• Status indicators: Approved, Reviewed, Published
• Feature flags: Has Priority Support, Requires Signature
• Simple tracking: Email Sent, Invoice Paid, Item Shipped

When NOT to Use Checkboxes

• When you need more than two options (use SELECT_SINGLE instead)
• For numeric or text data (use NUMBER or TEXT fields)
• When you need to track who checked it or when (use audit logs)

Common Use Cases

1. Approval Workflows

   • “Manager Approved”
   • “Client Sign-off”
   • “Legal Review Complete”

2. Task Management

   • “Is Blocked”
   • “Ready for Review”
   • “High Priority”

3. Quality Control

   • “QA Passed”
   • “Documentation Complete”
   • “Tests Written”

4. Administrative Flags

   • “Invoice Sent”
   • “Contract Signed”
   • “Follow-up Required”

Limitations

• Checkbox fields can only store true/false values (no tri-state or null after initial set)
• No default value configuration (always starts as null until set)
• Cannot store additional metadata like who checked it or when
• No conditional visibility based on other field values

Related Resources

• Custom Fields Overview - General custom field concepts
• Automations API - Create automations triggered by checkbox changes