> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check a formula before you save it

> Runs the check a save runs: syntax, the fields and relationships the formula names, the type it produces against `type`, loops through other formulas and complexity. An invalid formula is a 200 with `valid: false` and the reasons in `errors`. Saves nothing.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/formulas/validate
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/formulas/validate:
    post:
      tags:
        - fields
      summary: Check a formula before you save it
      description: >-
        Runs the check a save runs: syntax, the fields and relationships the
        formula names, the type it produces against `type`, loops through other
        formulas and complexity. An invalid formula is a 200 with `valid: false`
        and the reasons in `errors`. Saves nothing.
      operationId: fields_validate_formula
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                field_key:
                  anyOf:
                    - type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The field the formula is for, when it exists: a formula that
                    refers back to it is refused
                  title: Field Key
                formula:
                  description: >-
                    A formula: EQUATION (an expression over this record's
                    fields, e.g. `{arr} * 1.1`), ROLLUP (aggregate a field of
                    related records), CROSS_OBJECT (copy a field of one related
                    record) or TIME_CALCULATION (time since, until or between
                    dates). GET /v1/formulas/functions lists the expression
                    functions.
                  discriminator:
                    mapping:
                      CROSS_OBJECT: '#/components/schemas/CrossObjectFormula'
                      EQUATION: '#/components/schemas/EquationFormula'
                      ROLLUP: '#/components/schemas/RollupFormula'
                      TIME_CALCULATION: '#/components/schemas/TimeCalculationFormula'
                    propertyName: formula_type
                  oneOf:
                    - $ref: '#/components/schemas/EquationFormula'
                    - $ref: '#/components/schemas/RollupFormula'
                    - $ref: '#/components/schemas/CrossObjectFormula'
                    - $ref: '#/components/schemas/TimeCalculationFormula'
                  title: Formula
                object:
                  description: >-
                    The object the formula is on; one of: account, contact,
                    opportunity
                  title: Object
                  type: string
                type:
                  description: >-
                    The field's type (number, text, date, boolean, ...): the
                    formula must produce it
                  title: Type
                  type: string
              required:
                - object
                - type
                - formula
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateFormulaResponse'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    CrossObjectFormula:
      additionalProperties: false
      properties:
        execution_order:
          default: 0
          description: Order of execution for dependent formulas
          title: Execution Order
          type: integer
        formula_type:
          const: CROSS_OBJECT
          title: Formula Type
          type: string
        is_active:
          default: true
          description: Whether formula is active
          title: Is Active
          type: boolean
        relationship:
          description: Relationship name (e.g., csm, parent, owner)
          title: Relationship
          type: string
        source_entity:
          description: Source entity type to pull from (e.g., PEOPLE, ACCOUNT)
          title: Source Entity
          type: string
        source_field:
          description: Field to copy from related entity
          title: Source Field
          type: string
        transform:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Optional transform (e.g., SPLIT_FIRST, UPPER)
          title: Transform
      required:
        - formula_type
        - source_entity
        - relationship
        - source_field
      title: CrossObjectFormula
      type: object
    EquationFormula:
      additionalProperties: false
      properties:
        execution_order:
          default: 0
          description: Order of execution for dependent formulas
          title: Execution Order
          type: integer
        expression:
          description: Formula expression string
          title: Expression
          type: string
        formula_type:
          const: EQUATION
          title: Formula Type
          type: string
        is_active:
          default: true
          description: Whether formula is active
          title: Is Active
          type: boolean
        null_handling:
          $ref: '#/components/schemas/NullHandling'
          default: RETURN_NULL
          description: How to handle null values
      required:
        - formula_type
        - expression
      title: EquationFormula
      type: object
    RollupFormula:
      additionalProperties: false
      properties:
        aggregation:
          $ref: '#/components/schemas/AggregationType'
          description: Type of aggregation to perform
        execution_order:
          default: 0
          description: Order of execution for dependent formulas
          title: Execution Order
          type: integer
        filters:
          anyOf:
            - $ref: '#/components/schemas/RollupFilters'
            - type: 'null'
          default: null
          description: Which related records to aggregate
        formula_type:
          const: ROLLUP
          title: Formula Type
          type: string
        is_active:
          default: true
          description: Whether formula is active
          title: Is Active
          type: boolean
        related_entity:
          description: Related entity type to aggregate from (e.g., ACCOUNT, OPPORTUNITY)
          title: Related Entity
          type: string
        relationship:
          description: Relationship name (e.g., descendants, children, parent)
          title: Relationship
          type: string
        separator:
          default: ', '
          description: Separator for CONCAT aggregation
          title: Separator
          type: string
        source_field:
          description: Field to aggregate from related entities
          title: Source Field
          type: string
      required:
        - formula_type
        - aggregation
        - related_entity
        - relationship
        - source_field
      title: RollupFormula
      type: object
    TimeCalculationFormula:
      additionalProperties: false
      properties:
        calculation_type:
          $ref: '#/components/schemas/TimeCalculationType'
          description: Type of time calculation
        date_field:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Date field (for TIME_SINCE)
          title: Date Field
        end_field:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: End date field (for TIME_BETWEEN, TIME_UNTIL)
          title: End Field
        execution_order:
          default: 0
          description: Order of execution for dependent formulas
          title: Execution Order
          type: integer
        formula_type:
          const: TIME_CALCULATION
          title: Formula Type
          type: string
        is_active:
          default: true
          description: Whether formula is active
          title: Is Active
          type: boolean
        start_field:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Start date field (for TIME_BETWEEN)
          title: Start Field
        unit:
          $ref: '#/components/schemas/TimeUnit'
          default: DAYS
          description: Unit of time to return
      required:
        - formula_type
        - calculation_type
      title: TimeCalculationFormula
      type: object
    ValidateFormulaResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/FormulaIssue'
          title: Errors
          type: array
        referenced_fields:
          items:
            type: string
          title: Referenced Fields
          type: array
        valid:
          title: Valid
          type: boolean
        warnings:
          items:
            $ref: '#/components/schemas/FormulaIssue'
          title: Warnings
          type: array
      required:
        - valid
      title: ValidateFormulaResponse
      type: object
    NullHandling:
      description: How to handle null values in formula evaluation.
      enum:
        - RETURN_NULL
        - TREAT_AS_ZERO
        - SKIP
      title: NullHandling
      type: string
    AggregationType:
      description: Aggregation types for rollup formulas.
      enum:
        - SUM
        - COUNT
        - MIN
        - MAX
        - AVG
        - MEDIAN
        - FIRST
        - LAST
        - CONCAT
        - COLLECT_UNIQUE
      title: AggregationType
      type: string
    RollupFilters:
      additionalProperties: false
      properties:
        filter_conditions:
          description: The conditions a related record must meet
          items:
            $ref: '#/components/schemas/RollupFilterCondition'
          title: Filter Conditions
          type: array
        filter_logic:
          default: AND
          description: Logic to combine filters (AND/OR)
          title: Filter Logic
          type: string
      title: RollupFilters
      type: object
    TimeCalculationType:
      description: Types of time calculations.
      enum:
        - TIME_BETWEEN
        - TIME_SINCE
        - TIME_UNTIL
      title: TimeCalculationType
      type: string
    TimeUnit:
      description: Time units for date/time calculations.
      enum:
        - DAYS
        - HOURS
        - MINUTES
        - MONTHS
        - YEARS
      title: TimeUnit
      type: string
    FormulaIssue:
      properties:
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          title: Message
          type: string
        type:
          description: >-
            What is wrong, e.g. SYNTAX_ERROR, FIELD_NOT_FOUND,
            CIRCULAR_DEPENDENCY
          title: Type
          type: string
      required:
        - type
        - message
      title: FormulaIssue
      type: object
    RollupFilterCondition:
      additionalProperties: false
      properties:
        field:
          description: Field name to filter on
          title: Field
          type: string
        operator:
          description: Comparison operator (eq, ne, gt, lt, etc.)
          title: Operator
          type: string
        value:
          description: Value to compare against
          title: Value
      required:
        - field
        - operator
        - value
      title: RollupFilterCondition
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.