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

# Update a field definition's display name, visibility, or requiredness

> Changes display_name, hidden, mandatory and/or formula (a formula field's only) on an existing field of account, contact, opportunity, project, task or user: standard or custom on an account, a contact, an opportunity or a user, custom on a project or a task (their built-in fields are changed in the app's Object Manager), and on a custom object (display_name and mandatory). Only provided attributes change. Returns the field's definition as it now stands.



## OpenAPI

````yaml /api/statisfy-api.openapi.json patch /v1/fields/{field_key}
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/fields/{field_key}:
    patch:
      tags:
        - fields
      summary: Update a field definition's display name, visibility, or requiredness
      description: >-
        Changes display_name, hidden, mandatory and/or formula (a formula
        field's only) on an existing field of account, contact, opportunity,
        project, task or user: standard or custom on an account, a contact, an
        opportunity or a user, custom on a project or a task (their built-in
        fields are changed in the app's Object Manager), and on a custom object
        (display_name and mandatory). Only provided attributes change. Returns
        the field's definition as it now stands.
      operationId: fields_update
      parameters:
        - in: path
          name: field_key
          required: true
          schema:
            type: string
        - description: >-
            The object the field belongs to: one of account, contact,
            opportunity, project, task, user, or a custom object's key (GET
            /v1/objects lists them)
          in: query
          name: object
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - maxLength: 255
                      minLength: 1
                      type: string
                    - type: 'null'
                  default: null
                  title: Display Name
                formula:
                  anyOf:
                    - 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'
                    - type: 'null'
                  default: null
                  description: A formula field's new formula
                  title: Formula
                hidden:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                  default: null
                  title: Hidden
                mandatory:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                  default: null
                  title: Mandatory
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldDef'
          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
    FieldDef:
      properties:
        currency_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency Code
        formula:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Set on a formula field: how its value is computed, in the shape
            `formula` takes on POST /v1/fields
          title: Formula
        hidden:
          default: false
          title: Hidden
          type: boolean
        key:
          title: Key
          type: string
        kind:
          enum:
            - standard
            - custom
          title: Kind
          type: string
        label:
          title: Label
          type: string
        mandatory:
          default: false
          title: Mandatory
          type: boolean
        object:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The object whose id(s) the value holds: set on reference fields (one
            id) and on id lists such as a contact's accounts (type text_list)
          title: Object
        option_labels:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Option Labels
        options:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Options
        owner:
          default: statisfy
          enum:
            - statisfy
            - crm
            - warehouse
            - integration
            - ai
            - computed
          title: Owner
          type: string
        syncs_to_crm:
          default: false
          title: Syncs To Crm
          type: boolean
        type:
          title: Type
          type: string
        writable:
          default: false
          title: Writable
          type: boolean
      required:
        - key
        - label
        - type
        - kind
      title: FieldDef
      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
    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.