Number Custom Field

A number custom field stores a numeric value on a record — quantities, scores, measurements, or any plain number. It maps to the NUMBER value of the CustomFieldType enum and is backed by a CustomField whose value is exposed as a Float. For monetary values use the Currency field; for percentages use the Percent field.

Records are Record objects in the API.

Overview

• Type enum: NUMBER
• Optional config: min / max bounds (Float) and a display prefix (String, e.g. #).
• Value shape: a single Float. On a record, read it from CustomField.number (or CustomField.value, which returns the same bare number for this type).
• Bounds enforcement: min/max are enforced when you create a record with createRecord (out-of-range values throw CUSTOM_FIELD_VALUE_PARSE_ERROR). They are not enforced by setRecordCustomField — see Notes.

Create

Use the createCustomField mutation with type: NUMBER. The field is created in the workspace named by your blue-workspace-id header — there is no projectId argument.

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

Add min, max, and a prefix to bound and decorate the field:

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

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Team Size",
      "type": "NUMBER",
      "min": 1,
      "max": 100,
      "prefix": "#",
      "description": "Number of people assigned to this work"
    }
  }
}

CreateCustomFieldInput

The workspace is taken from the blue-workspace-id header (ID or slug); CreateCustomFieldInput has no projectId field.

Set a value

Use the setRecordCustomField mutation with the number argument. It returns Boolean! — true on success — so it has no sub-selection.

mutation SetNumberValue {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", number: 42.5 })
}

{ "data": { "setRecordCustomField": true } }

SetRecordCustomFieldInput

Read a value

setRecordCustomField returns only a boolean, so read the stored value back through the record’s customFields connection. Record.customFields returns [CustomField!]! directly — select the value fields on the element. For a NUMBER field, both number and value resolve to the bare numeric value.

query ReadNumberValue {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoIds: ["todo_123"] }) {
      items {
        id
        title
        customFields {
          id
          name
          type
          number
          value
        }
      }
    }
  }
}

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Performance Review",
            "customFields": [
              {
                "id": "clm4n8qwx000108l0a1b2c3d4",
                "name": "Priority Score",
                "type": "NUMBER",
                "number": 42.5,
                "value": 42.5
              }
            ]
          }
        ]
      }
    }
  }
}

The number and value fields resolve only when the CustomField is read in a record context (via Record.customFields); they are null when the field definition is read on its own. If no value is set, both return null.

Set a value at record creation

createRecord accepts custom-field values inline through CreateRecordInputCustomField, which carries the value as a string in the value field (there is no number argument here). The string is parsed to a number, and min/max are enforced — an out-of-range or non-numeric value throws CUSTOM_FIELD_VALUE_PARSE_ERROR.

mutation CreateRecordWithNumber {
  createRecord(
    input: {
      title: "Performance Review"
      todoListId: "list_123"
      customFields: [{ customFieldId: "field_123", value: "85.5" }]
    }
  ) {
    id
    title
    customFields {
      name
      type
      number
    }
  }
}

Notes

• Bounds are enforced only at record creation. createRecord parses the inline string value and rejects anything below min, above max, or non-numeric with CUSTOM_FIELD_VALUE_PARSE_ERROR. setRecordCustomField writes the number argument straight to storage with no bounds check — a value outside min/max is accepted and stored. Enforce bounds client-side when calling setRecordCustomField.
• prefix is display-only. It is returned on the field definition for clients to render; it is not part of the stored value.
• Filtering by value is done through the fields JSON of TodosFilter (a CUSTOM_FIELD entry with customFieldType: "NUMBER"), not through per-field operators. See List records for the full fields filter shape.

query FilterByNumber {
  recordQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_123"]
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "field_123"
            customFieldType: "NUMBER"
            values: ["80"]
            op: "GTE"
          }
        ]
      }
    ) {
      items {
        id
        title
      }
    }
  }
}

Errors

Permissions

• Create the field: createCustomField requires the OWNER or ADMIN role on the workspace.
• Set a value: setRecordCustomField requires an authenticated caller with edit access to the record (any company role, or a custom project role granting edit on the field).

Related

• Set custom field values
• Currency field
• Percent field
• Rating field
• List records
• Custom Fields overview