Skip to main content
The Number field captures numeric values — integers or decimals — with optional formatting and validation. Number fields enable calculations, comparisons, and numeric operations within automations and data processing. Use Number fields whenever you need to perform mathematical operations, apply min/max validation, or format values as currency or percentages. Number fields are essential for financial data, quantities, ages, scores, and any data that requires numeric processing.

​
When to Use

Use Number fields for:
  • Financial amounts (prices, costs, revenues, claims)
  • Quantities (items, count, volume)
  • Ages and years
  • Scores and ratings
  • Percentages and ratios
  • Measurements (weight, height, distance)
  • Identifiers that are purely numeric (account numbers, IDs)
  • Calculated values
Consider alternatives:
  • Use Text for alphanumeric IDs (contain letters)
  • Use Choices for predefined numeric ranges (age groups, price tiers)
  • Use Date for years that represent dates

​
Configuration Options

OptionDescriptionTypeDefaultExample
keyUnique identifierStringRequiredannual_revenue
nameDisplay labelStringRequired”Annual Revenue”
descriptionHelp text for usersStringOptional”Company revenue for last fiscal year”
ai_descriptionHint for IntelligenceStringOptional”Total annual revenue in euros”
minMinimum allowed valueNumberNone0
maxMaximum allowed valueNumberNone1000000
stepIncrement stepNumber10.01 for decimals
formatDisplay formatStringNonecurrency, percentage
currencyCurrency code (if format=currency)StringEURUSD, GBP
decimalsNumber of decimal placesNumber02
visibilityDisplay settingStringalways-visiblehide-when-empty
sectionSection this field belongs toStringNoneSection UUID

​
Examples

​
Basic Integer

Collect a simple count: 
{
  "key": "number_of_employees",
  "type": "number",
  "name": "Number of Employees",
  "description": "Total full-time employees",
  "min": 1,
  "ai_description": "The total number of full-time employees currently working at the company"
}

​
Currency Amount

Collect monetary value with currency formatting: 
{
  "key": "claim_amount",
  "type": "number",
  "name": "Claim Amount",
  "description": "Total claim value in euros",
  "format": "currency",
  "currency": "EUR",
  "decimals": 2,
  "min": 0,
  "max": 1000000,
  "ai_description": "The total monetary amount being claimed, expressed in euros, typically found in the claim summary or financial section"
}

​
Percentage

Collect percentage values: 
{
  "key": "completion_percentage",
  "type": "number",
  "name": "Completion Percentage",
  "description": "Project completion percentage",
  "format": "percentage",
  "min": 0,
  "max": 100,
  "step": 5
}

​
Decimal Value

Collect precise measurements: 
{
  "key": "weight_kg",
  "type": "number",
  "name": "Weight (kg)",
  "description": "Weight in kilograms",
  "decimals": 2,
  "step": 0.01,
  "min": 0,
  "ai_description": "Weight measurement in kilograms with two decimal places"
}

​
Validation

Number fields enforce numeric validation automatically:

​
Type Validation

  • Only numeric values accepted
  • Decimals allowed based on step and decimals configuration
  • Non-numeric input rejected

​
Range Validation

  • min - Minimum allowed value (inclusive)
  • max - Maximum allowed value (inclusive)
  • User cannot enter values outside range

​
Step Validation

  • step defines increment granularity
  • For integers: step: 1 (default)
  • For decimals: step: 0.01 allows two decimal places
  • User input rounded to nearest step
Validation happens when users fill the field. Existing data or API imports are not automatically validated.

​
AI Descriptions

AI descriptions help Intelligence extract numeric data from emails and documents. For number fields: Be specific about:
  • Units (euros, dollars, kilograms, years)
  • Context (annual revenue vs monthly revenue)
  • Format (with or without decimals)
  • Where the number typically appears
Good AI descriptions for number fields:
FieldAI Description
annual_revenue”The company’s total annual revenue in euros for the most recent fiscal year, typically found in financial statements”
claim_amount”The total monetary amount being claimed in euros, found in the claim summary or financial breakdown section”
number_of_employees”The total number of full-time equivalent employees currently working at the company”
age”The person’s age in years at the time of application”
loan_amount”The requested loan amount in euros, excluding fees and interest”
Include units in AI descriptions:
  • Always specify currency (euros, dollars, pounds)
  • Specify measurement units (kilograms, meters, years)
  • Clarify if the value is total, annual, monthly, etc.
Including units and context in AI descriptions dramatically improves Intelligence accuracy when extracting numeric data from documents.

​
Formatting

​
Currency Formatting

Display values as currency: 
{
  "format": "currency",
  "currency": "EUR",
  "decimals": 2
}
Result: €1,234.56 (format depends on locale) Supported currencies:
  • EUR (Euro)
  • USD (US Dollar)
  • GBP (British Pound)
  • CHF (Swiss Franc)
  • And all standard ISO 4217 currency codes

​
Percentage Formatting

Display values as percentages: 
{
  "format": "percentage",
  "decimals": 1
}
Result: 75.5%

​
Number Formatting

Standard numeric display: 
{
  "decimals": 2
}
Result: 1,234.56 (thousands separator, 2 decimal places)

​
Calculations

Number fields can be used in calculations within automations and workflows: Common calculations:
  • Sum multiple fields
  • Calculate percentages
  • Apply multipliers or rates
  • Compare values for conditional logic
  • Determine ranges or thresholds
Example: Calculate total from line items, apply discount rate, determine if amount exceeds threshold.
Calculation logic is defined in penscript automations. See the penscript documentation for calculation syntax.

​
Best Practices

Always use Number for numeric data:
  • Don’t store numbers as text (prevents calculations)
  • Use Number even if you don’t need calculations now (future-proofs)
  • Enables numeric comparisons in automations
Set appropriate min/max:
  • Prevents invalid or unrealistic values
  • Catches data entry errors
  • Useful for regulated fields with limits
Configure decimals based on needs:
  • Use 0 decimals for counts and quantities
  • Use 2 decimals for currency
  • Use appropriate precision for measurements
Format currency consistently:
  • Always specify currency for amounts
  • Use workspace default currency when possible
  • Be explicit in field name (“Amount (EUR)”)
Validate reasonably:
  • Don’t set overly restrictive min/max
  • Consider edge cases (zero values, large amounts)
  • Test with realistic data ranges

Text

Use for alphanumeric IDs and formatted numbers

Choices

Use for predefined numeric ranges or tiers

Date

Use for year values that represent dates

Data Schema Overview

Back to Data Schema overview