Number Custom Field

Number custom fields allow you to store numeric values for records. They support validation constraints, decimal precision, and can be used for quantities, scores, measurements, or any numeric data that doesn’t require special formatting.

Basic Example

Create a simple number field:

mutation CreateNumberField {
  createCustomField(input: {
    name: "Priority Score"
    type: NUMBER
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a number field with constraints and prefix:

mutation CreateConstrainedNumberField {
  createCustomField(input: {
    name: "Team Size"
    type: NUMBER
    projectId: "proj_123"
    min: 1
    max: 100
    prefix: "#"
    description: "Number of team members assigned to this project"
  }) {
    id
    name
    type
    min
    max
    prefix
    description
  }
}

Input Parameters

CreateCustomFieldInput

Setting Number Values

Number fields store decimal values with optional validation:

Simple Number Value

mutation SetNumberValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 42.5
  })
}

Integer Value

mutation SetIntegerValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 100
  })
}

SetTodoCustomFieldInput Parameters

Value Constraints

Min/Max Constraints (UI Guidance)

Important: Min/max constraints are stored but NOT enforced server-side. They serve as UI guidance for frontend applications.

mutation CreateConstrainedField {
  createCustomField(input: {
    name: "Rating"
    type: NUMBER
    projectId: "proj_123"
    min: 1
    max: 10
    description: "Rating from 1 to 10"
  }) {
    id
    name
    min
    max
  }
}

Client-Side Validation Required: Frontend applications must implement validation logic to enforce min/max constraints.

Supported Value Types

Note: Min/max constraints are NOT validated server-side. Values outside the specified range will be accepted and stored.

Creating Records with Number Values

When creating a new record with number values:

mutation CreateRecordWithNumber {
  createTodo(input: {
    title: "Performance Review"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "score_field_id"
      number: 85.5
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        min
        max
        prefix
      }
      number
      value
    }
  }
}

Supported Input Formats

When creating records, use the number parameter (not value) in the custom fields array:

customFields: [{
  customFieldId: "field_id"
  number: 42.5  # Use number parameter, not value
}]

Response Fields

TodoCustomField Response

CustomField Response

Note: If the number value is not set, the number field will be null.

Filtering and Querying

Number fields support comprehensive numeric filtering:

query FilterByNumberRange {
  todos(filter: {
    customFields: [{
      customFieldId: "score_field_id"
      operator: GTE
      number: 80
    }]
  }) {
    id
    title
    customFields {
      number
    }
  }
}

Supported Operators

Range Filtering

query FilterByRange {
  todos(filter: {
    customFields: [{
      customFieldId: "priority_field_id"
      operator: GTE
      number: 5
    }]
  }) {
    id
    title
  }
}

Display Formatting

With Prefix

If a prefix is set, it will be displayed:

Decimal Precision

Numbers maintain their decimal precision:

Required Permissions

Error Responses

Invalid Number Format

{
  "errors": [{
    "message": "Invalid number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Field Not Found

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

Note: Min/max validation errors do NOT occur server-side. Constraint validation must be implemented in your frontend application.

Not a Number

{
  "errors": [{
    "message": "Value is not a valid number",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Best Practices

Constraint Design

• Set realistic min/max values for UI guidance
• Implement client-side validation to enforce constraints
• Use constraints to provide user feedback in forms
• Consider if negative values are valid for your use case

Value Precision

• Use appropriate decimal precision for your needs
• Consider rounding for display purposes
• Be consistent with precision across related fields

Display Enhancement

• Use meaningful prefixes for context
• Consider units in field names (e.g., “Weight (kg)”)
• Provide clear descriptions for validation rules

Common Use Cases

1. Scoring Systems

   • Performance ratings
   • Quality scores
   • Priority levels
   • Customer satisfaction ratings

2. Measurements

   • Quantities and amounts
   • Dimensions and sizes
   • Durations (in numeric format)
   • Capacities and limits

3. Business Metrics

   • Revenue figures
   • Conversion rates
   • Budget allocations
   • Target numbers

4. Technical Data

   • Version numbers
   • Configuration values
   • Performance metrics
   • Threshold settings

Integration Features

With Charts and Dashboards

• Use NUMBER fields in chart calculations
• Create numerical visualizations
• Track trends over time

With Automations

• Trigger actions based on number thresholds
• Update related fields based on number changes
• Send notifications for specific values

With Lookups

• Aggregate numbers from related records
• Calculate totals and averages
• Find min/max values across relationships

With Charts

• Create numerical visualizations
• Track trends over time
• Compare values across records

Limitations

• No server-side validation of min/max constraints
• Client-side validation required for constraint enforcement
• No built-in currency formatting (use CURRENCY type instead)
• No automatic percentage symbol (use PERCENT type instead)
• No unit conversion capabilities
• Decimal precision limited by database Decimal type
• No mathematical formula evaluation in the field itself

Related Resources

• Custom Fields Overview - General custom field concepts
• Currency Custom Field - For monetary values
• Percent Custom Field - For percentage values
• Automations API - Create number-based automations