> ## 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.

# Compute a formula on a few records without saving it

> Checks the formula as a save would, then computes it on up to 50 records (`record_ids`). Each result has the record's name and the value, or the reason it has none (a record that is not found). Needs the object's read scope too (`accounts:read`, `contacts:read` or `opportunities:read`). Saves nothing.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/formulas/preview
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/preview:
    post:
      tags:
        - fields
      summary: Compute a formula on a few records without saving it
      description: >-
        Checks the formula as a save would, then computes it on up to 50 records
        (`record_ids`). Each result has the record's name and the value, or the
        reason it has none (a record that is not found). Needs the object's read
        scope too (`accounts:read`, `contacts:read` or `opportunities:read`).
        Saves nothing.
      operationId: fields_preview_formula
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                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
                record_ids:
                  description: The records to compute the formula on
                  items:
                    type: string
                  maxItems: 50
                  minItems: 1
                  title: Record Ids
                  type: array
                type:
                  description: >-
                    The field's type (number, text, date, boolean, ...): the
                    formula must produce it
                  title: Type
                  type: string
              required:
                - object
                - type
                - formula
                - record_ids
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewFormulaResponse'
          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
    PreviewFormulaResponse:
      properties:
        errors:
          description: Set when the formula is not valid
          items:
            $ref: '#/components/schemas/FormulaIssue'
          title: Errors
          type: array
        results:
          items:
            $ref: '#/components/schemas/PreviewRow'
          title: Results
          type: array
        valid:
          title: Valid
          type: boolean
      required:
        - valid
      title: PreviewFormulaResponse
      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
    PreviewRow:
      properties:
        error:
          anyOf:
            - type: string
            - type: 'null'
          description: Why this record has no value, e.g. it was not found
          title: Error
        id:
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        value:
          title: Value
      required:
        - id
      title: PreviewRow
      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.