---

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

Parameter	Type	Required	Description
name	String!	✅ Yes	Display name of the number field
type	CustomFieldType!	✅ Yes	Must be NUMBER
projectId	String!	✅ Yes	ID of the project to create the field in
min	Float	No	Minimum value constraint (UI guidance only)
max	Float	No	Maximum value constraint (UI guidance only)
prefix	String	No	Display prefix (e.g., "#", "~", "$")
description	String	No	Help text shown to users

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

Parameter	Type	Required	Description
todoId	String!	✅ Yes	ID of the record to update
customFieldId	String!	✅ Yes	ID of the number custom field
number	Float	No	Numeric value to store

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

Type	Example	Description
Integer	42	Whole numbers
Decimal	42.5	Numbers with decimal places
Negative	-10	Negative values (if no min constraint)
Zero	0	Zero value

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

Field	Type	Description
id	String!	Unique identifier for the field value
customField	CustomField!	The custom field definition
number	Float	The numeric value
todo	Todo!	The record this value belongs to
createdAt	DateTime!	When the value was created
updatedAt	DateTime!	When the value was last modified

CustomField Response

Field	Type	Description
id	String!	Unique identifier for the field definition
name	String!	Display name of the field
type	CustomFieldType!	Always NUMBER
min	Float	Minimum allowed value
max	Float	Maximum allowed value
prefix	String	Display prefix
description	String	Help text

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

Operator	Description	Example
EQ	Equal to	number = 42
NE	Not equal to	number ≠ 42
GT	Greater than	number > 42
GTE	Greater than or equal	number ≥ 42
LT	Less than	number < 42
LTE	Less than or equal	number ≤ 42
IN	In array	number in [1, 2, 3]
NIN	Not in array	number not in [1, 2, 3]
IS	Is null/not null	number is null

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:

Value	Prefix	Display
42	"#"	#42
100	"~"	~100
3.14	"π"	π3.14

Decimal Precision

Numbers maintain their decimal precision:

Input	Stored	Displayed
42	42.0	42
42.5	42.5	42.5
42.123	42.123	42.123

Required Permissions

Action	Required Permission
Create number field	Company role: OWNER or ADMIN
Update number field	Company role: OWNER or ADMIN
Set number value	Any company role (OWNER, ADMIN, MEMBER, CLIENT) or custom project role with edit permission
View number value	Standard record view permissions
Use in filtering	Standard record view 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