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

# Set Entity Type Field Formula

> Set how an entity type field gets its value. value_source COMPUTED with formula makes the formula own the value: callers can no longer write it, it reruns whenever a field it reads changes, and saving it recomputes every existing entity in the background, overwriting entered values (an empty result clears them). AUTO_NUMBER with auto_number numbers every entity, existing ones without a value included, as prefix plus a zero-padded counter; only TEXT and UNIQUE fields can be auto-numbered. ENTERED makes the field writable again, keeping the last values; add default_formula to fill it on create when the caller leaves it empty. Call on the field ID of the type that defines the field, not a child type that inherits it. Fields used by an ingestion mapping or a normalization rule, the key field of an ingested type, and formulas that read a sensitive field into a non-sensitive one are refused. Check a formula first with Preview Entity Type Field Formula, and follow the recompute with Get Entity Type Field Formula Status. Formulas are CEL over the entity's own fields, each named by its key with hyphens written as underscores (item-cost is item_cost). An empty field is null: test it with has(x) or supply a fallback with x.orValue(d). A single-target ENTITY_REF field reads one level through the reference (owner.email); an ENUM field reads as {key, label}. Functions: join_nonempty(sep, list), round(x), round(x, digits), string, today(), days_between(a, b), lower, upper, the ? : operator, and the exists and all macros. A computed field may read another computed field only when that one reads none, cycles are refused, and a formula reads at most 10 referenced fields. FILE and MULTI_SELECT fields cannot be read or produced.

## Authentication and permissions

> **Token requirements:** **User-based token (OAuth)** or **Organization-scoped API key** or **Team-scoped API key**.
>
> Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

| Credential | Access requirements |
| - | - |
| Organization-scoped API key | `entities:write` |
| Team-scoped API key | `entities:write` |
| User-based token (OAuth) | Supported, subject to permissions |

Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access.

* **Change how a field in a team's database gets its value:** The permission is checked on the team that owns the field's database. A caller admitted to the database only through a share cannot change its formulas.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml put /v2/entity-type-fields/{id}/formula
openapi: 3.1.0
info:
  title: Serval Public API
  description: Serval Public API
  contact:
    name: Serval
    url: https://serval.com
    email: support@serval.com
  license:
    name: Serval License
    url: https://serval.com/license
  version: 2.0.0
servers:
  - url: https://public.api.serval.com
security:
  - BearerAuth: []
tags:
  - name: Access Membership API
  - name: Access Policy API
  - name: Access Policy Approval Procedure API
  - name: Access Profile API
  - name: Access Relationship API
  - name: Access Request API
  - name: Agent API
  - name: Analytics API
  - name: App Instance API
  - name: App Resource API
  - name: App Resource Role API
  - name: Approval Delegation API
  - name: Approval Procedure API
  - name: Approval Request API
  - name: Assignment Rules API
  - name: Audit Log API
  - name: Billing API
  - name: Browser API
  - name: Campaign API
  - name: Change Blackout API
  - name: Change Model API
  - name: Connected Channels API
  - name: Custom Field API
  - name: Custom Role API
  - name: Custom Service API
  - name: Dashboards API
  - name: Email Intake API
  - name: Entity API
  - name: Entity Field Mapping API
  - name: Entity Ingestion Config API
  - name: Entity Type API
  - name: Folder API
  - name: Forms API
  - name: Group API
  - name: Guidance API
  - name: Help Agent API
  - name: Improvement Request API
  - name: Journey API
  - name: Knowledge API
  - name: Knowledge Base API
  - name: One-Time Window API
  - name: Package API
  - name: Report API
  - name: Review API
  - name: Roles API
  - name: SLA API
  - name: Schedule API
  - name: Tag API
  - name: Team API
  - name: Team Group API
  - name: Team SDLC Settings API
  - name: Team User API
  - name: Ticket API
  - name: Ticket Import API
  - name: Topic API
  - name: User API
  - name: User Relationship API
  - name: Widgets API
  - name: Worker API
  - name: Workflow API
  - name: Workflow Approval Procedure API
  - name: Workflow Run API
paths:
  /v2/entity-type-fields/{id}/formula:
    put:
      tags:
        - Entity Type API
      summary: Set Entity Type Field Formula
      description: >-
        Set how an entity type field gets its value. value_source COMPUTED with
        formula makes the formula own the value: callers can no longer write it,
        it reruns whenever a field it reads changes, and saving it recomputes
        every existing entity in the background, overwriting entered values (an
        empty result clears them). AUTO_NUMBER with auto_number numbers every
        entity, existing ones without a value included, as prefix plus a
        zero-padded counter; only TEXT and UNIQUE fields can be auto-numbered.
        ENTERED makes the field writable again, keeping the last values; add
        default_formula to fill it on create when the caller leaves it empty.
        Call on the field ID of the type that defines the field, not a child
        type that inherits it. Fields used by an ingestion mapping or a
        normalization rule, the key field of an ingested type, and formulas that
        read a sensitive field into a non-sensitive one are refused. Check a
        formula first with Preview Entity Type Field Formula, and follow the
        recompute with Get Entity Type Field Formula Status. Formulas are CEL
        over the entity's own fields, each named by its key with hyphens written
        as underscores (item-cost is item_cost). An empty field is null: test it
        with has(x) or supply a fallback with x.orValue(d). A single-target
        ENTITY_REF field reads one level through the reference (owner.email); an
        ENUM field reads as {key, label}. Functions: join_nonempty(sep, list),
        round(x), round(x, digits), string, today(), days_between(a, b), lower,
        upper, the ? : operator, and the exists and all macros. A computed field
        may read another computed field only when that one reads none, cycles
        are refused, and a formula reads at most 10 referenced fields. FILE and
        MULTI_SELECT fields cannot be read or produced.
      operationId: svrelay.publicv2.PublicAPIServiceV2.SetEntityTypeFieldFormula
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: id
            description: >-
              The ID of the entity type field on the type that defines it. A
              field a
               type inherits takes its formula from the parent's placement.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                valueSource:
                  $ref: '#/components/schemas/svstore.FieldValueSource'
                  title: value_source
                  description: >-
                    ENTERED (callers write the value), COMPUTED (formula owns
                    the value) or
                     AUTO_NUMBER (a counter numbers each record).
                formula:
                  type:
                    - string
                    - 'null'
                  title: formula
                  description: >-
                    The formula. Required when value_source is COMPUTED; refused
                    otherwise.
                defaultFormula:
                  type:
                    - string
                    - 'null'
                  title: default_formula
                  description: >-
                    A formula that fills the field on create when the caller
                    leaves it
                     empty. ENTERED only; omit to clear the field's default.
                autoNumber:
                  oneOf:
                    - $ref: '#/components/schemas/svstore.AutoNumberSettings'
                    - type: 'null'
                  title: auto_number
                  description: >-
                    Required when value_source is AUTO_NUMBER; refused
                    otherwise.
              title: SetEntityTypeFieldFormulaRequest
              additionalProperties: false
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/svstore.publicapi.SetEntityTypeFieldFormulaResponse
      security:
        - BearerAuth: []
components:
  schemas:
    svstore.FieldValueSource:
      type: string
      title: FieldValueSource
      enum:
        - FIELD_VALUE_SOURCE_UNSPECIFIED
        - FIELD_VALUE_SOURCE_ENTERED
        - FIELD_VALUE_SOURCE_COMPUTED
        - FIELD_VALUE_SOURCE_AUTO_NUMBER
    svstore.AutoNumberSettings:
      type: object
      properties:
        prefix:
          type: string
          title: prefix
          description: empty means none
          x-stainless-terraform-configurability: optional
        digits:
          type: integer
          title: digits
          format: int32
          description: 1-18
          x-stainless-terraform-configurability: optional
        scope:
          $ref: '#/components/schemas/svstore.AutoNumberScope'
          title: scope
          x-stainless-terraform-configurability: optional
      title: AutoNumberSettings
      additionalProperties: false
      description: |-
        How an auto-numbered field builds its values: the prefix followed by the
         next number, zero-padded to digits.
    svstore.publicapi.SetEntityTypeFieldFormulaResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/svstore.EntityTypeField'
          title: data
          description: The field as saved.
          x-stainless-terraform-configurability: optional
      title: SetEntityTypeFieldFormulaResponse
      additionalProperties: false
    svstore.AutoNumberScope:
      type: string
      title: AutoNumberScope
      enum:
        - AUTO_NUMBER_SCOPE_UNSPECIFIED
        - AUTO_NUMBER_SCOPE_TYPE
        - AUTO_NUMBER_SCOPE_SCHEMA
      description: Which records share an auto-numbered field's counter.
    svstore.EntityTypeField:
      type: object
      properties:
        id:
          type: string
          title: id
          x-stainless-terraform-configurability: optional
        entityTypeId:
          type: string
          title: entity_type_id
          x-stainless-terraform-configurability: optional
        key:
          type: string
          title: key
          x-stainless-terraform-configurability: optional
        name:
          type: string
          title: name
          x-stainless-terraform-configurability: optional
        dataType:
          $ref: '#/components/schemas/svstore.EntityTypeField.DataType'
          title: data_type
          x-stainless-terraform-configurability: optional
        createdAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
          x-stainless-terraform-configurability: optional
        updatedAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: updated_at
          x-stainless-terraform-configurability: optional
        createdByUserId:
          type: string
          title: created_by_user_id
          x-stainless-terraform-configurability: optional
        updatedByUserId:
          type: string
          title: updated_by_user_id
          x-stainless-terraform-configurability: optional
        enumOptions:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EnumOption'
          title: enum_options
          x-stainless-terraform-configurability: optional
        isKeyField:
          type: boolean
          title: is_key_field
          description: >-
            Whether this field's value drives the entity's key (dedup
            identifier).
             Must be a UNIQUE data type field. At most one per entity type.
          x-stainless-terraform-configurability: computed_optional
        isNameField:
          type: boolean
          title: is_name_field
          description: Whether this field's value drives the entity's display name.
          x-stainless-terraform-configurability: computed_optional
        fieldId:
          type: string
          title: field_id
          description: >-
            The field definition this binding references (entity_fields id). A
            field
             and its inherited copies across a type hierarchy share one definition.
          x-stainless-terraform-configurability: optional
        refEntityTypeId:
          type:
            - string
            - 'null'
          title: ref_entity_type_id
          description: |-
            For ENTITY_REF fields: the first allowed target entity type. Kept in
             lockstep with ref_entity_type_ids for readers that predate the set;
             prefer ref_entity_type_ids.
          x-stainless-terraform-configurability: optional
        refEntityTypeIds:
          type: array
          items:
            type: string
          title: ref_entity_type_ids
          description: |-
            For ENTITY_REF fields: the entity types values may reference. Empty
             means any type. Supersedes ref_entity_type_id.
          x-stainless-terraform-configurability: optional
        description:
          type:
            - string
            - 'null'
          title: description
          x-stainless-terraform-configurability: optional
        sourceEntityTypeId:
          type:
            - string
            - 'null'
          title: source_entity_type_id
          description: |-
            If set, this field is inherited from the specified entity type.
             Empty means the field is defined directly on this entity type.
          x-stainless-terraform-configurability: optional
        viewerCanViewValues:
          type:
            - boolean
            - 'null'
          title: viewer_can_view_values
          description: >-
            Per-field viewer capabilities, same contract as EntityType's: the
            def
             is always listed; false can_view_values means values are hidden for
             this viewer, false can_edit means read-only.
          x-stainless-terraform-configurability: optional
        viewerCanEdit:
          type:
            - boolean
            - 'null'
          title: viewer_can_edit
          x-stainless-terraform-configurability: optional
        helpAgentVisible:
          type: boolean
          title: help_agent_visible
          description: >-
            Whether the help agent may read this field's values. Retrieval
            policy on
             top of access rules (the agent already reads as the ticket requester):
             false drops the field from agent documents, prompts, and search filters.
             A definition property: field_id is also the scope key for field-level
             access rules.
          x-stainless-terraform-configurability: computed_optional
        sensitive:
          type: boolean
          title: sensitive
          description: |-
            Whether this field's values are sensitive: every read withholds them
             (EntityFieldValue.sensitive marks the placement) and a caller who may
             read the field reveals one entity's value at a time through
             RevealEntityFieldValue, which is audited. A definition property, like
             help_agent_visible. Key, name, and relationship endpoint fields cannot
             be sensitive.
          x-stainless-terraform-configurability: computed_optional
        sectionId:
          type:
            - string
            - 'null'
          title: section_id
          description: >-
            Visual grouping for the entity detail UI. Unset means the field
            renders
             in the implicit "Overview" tab.
          x-stainless-terraform-configurability: optional
        displayOptions:
          oneOf:
            - $ref: '#/components/schemas/svstore.FieldDisplayOptions'
            - type: 'null'
          title: display_options
          description: How values render. Unset means the data type's default presentation.
          x-stainless-terraform-configurability: optional
        valueSource:
          $ref: '#/components/schemas/svstore.FieldValueSource'
          title: value_source
          x-stainless-terraform-configurability: optional
        formula:
          type:
            - string
            - 'null'
          title: formula
          description: >-
            CEL over the record's fields by key; set when value_source is
            COMPUTED.
          x-stainless-terraform-configurability: optional
        defaultFormula:
          type:
            - string
            - 'null'
          title: default_formula
          description: CEL that fills the field on create when the caller leaves it empty.
          x-stainless-terraform-configurability: optional
        formulaDisabledAt:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: formula_disabled_at
          description: >-
            Set when a schema change removed a field the formula reads. The
            formula
             does not run again until it is saved.
          x-stainless-terraform-configurability: optional
        autoNumber:
          oneOf:
            - $ref: '#/components/schemas/svstore.AutoNumberSettings'
            - type: 'null'
          title: auto_number
          description: Set exactly when value_source is AUTO_NUMBER.
          x-stainless-terraform-configurability: optional
        timestampRange:
          oneOf:
            - $ref: '#/components/schemas/svstore.TimestampRangeSettings'
            - type: 'null'
          title: timestamp_range
          description: Set exactly when data_type is TIMESTAMP_RANGE.
          x-stainless-terraform-configurability: optional
      title: EntityTypeField
      additionalProperties: false
    svstore.EntityTypeField.DataType:
      type: string
      title: DataType
      enum:
        - DATA_TYPE_UNSPECIFIED
        - TEXT
        - NUMBER
        - BOOL
        - TIMESTAMP
        - ENUM
        - ENTITY_REF
        - USER_REF
        - UNIQUE
        - MULTI_SELECT
        - FILE
        - TICKET_REF
        - TIMESTAMP_RANGE
    google.protobuf.Timestamp:
      type: string
      examples:
        - '2025-01-15T01:30:15.000Z'
        - '2025-06-01T00:00:00.000Z'
      format: date-time
      description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
    svstore.EnumOption:
      type: object
      properties:
        id:
          type: string
          title: id
          x-stainless-terraform-configurability: optional
        value:
          type: string
          title: value
          x-stainless-terraform-configurability: optional
        displayName:
          type: string
          title: display_name
          x-stainless-terraform-configurability: optional
        displayOrder:
          type: integer
          title: display_order
          format: int32
          x-stainless-terraform-configurability: optional
        description:
          type: string
          title: description
          description: |-
            What the option means. Shown to admins and given to AI custom-field
             inference so it can choose between options by meaning, not just name.
          x-stainless-terraform-configurability: optional
      title: EnumOption
      additionalProperties: false
    svstore.FieldDisplayOptions:
      type: object
      oneOf:
        - $ref: '#/components/schemas/svstore.FieldDisplayOptions.Boolean'
        - $ref: '#/components/schemas/svstore.FieldDisplayOptions.Number'
        - $ref: '#/components/schemas/svstore.FieldDisplayOptions.Text'
        - $ref: '#/components/schemas/svstore.FieldDisplayOptions.Timestamp'
      title: FieldDisplayOptions
      description: >-
        FieldDisplayOptions is presentation config: it changes how a stored
        value is
         rendered, never what is stored. The set variant must match the field's data
         type — a NUMBER field carrying `timestamp` options is rejected at write time
         rather than silently ignored.

         Like data_type, this belongs to the field CONCEPT, so it is
         held identical across a field group (a field plus its inherited copies).
    svstore.TimestampRangeSettings:
      type: object
      properties:
        allowsOpenEnd:
          type: boolean
          title: allows_open_end
          description: >-
            Whether a value may leave its end null while its window has not
            ended.
             Off by default: every value needs both ends.
          x-stainless-terraform-configurability: computed_optional
      title: TimestampRangeSettings
      additionalProperties: false
      description: |-
        Which TIMESTAMP_RANGE values a field accepts. A property of the field
         definition, shared by the field and its inherited copies.
    svstore.FieldDisplayOptions.Boolean:
      type: object
      title: Boolean
      properties:
        boolean:
          $ref: '#/components/schemas/svstore.BoolDisplayOptions'
          title: boolean
          x-stainless-terraform-configurability: optional
      required:
        - boolean
      additionalProperties: false
    svstore.FieldDisplayOptions.Number:
      type: object
      title: Number
      properties:
        number:
          $ref: '#/components/schemas/svstore.NumberDisplayOptions'
          title: number
          x-stainless-terraform-configurability: optional
      required:
        - number
      additionalProperties: false
    svstore.FieldDisplayOptions.Text:
      type: object
      title: Text
      properties:
        text:
          $ref: '#/components/schemas/svstore.TextDisplayOptions'
          title: text
          x-stainless-terraform-configurability: optional
      required:
        - text
      additionalProperties: false
    svstore.FieldDisplayOptions.Timestamp:
      type: object
      title: Timestamp
      properties:
        timestamp:
          $ref: '#/components/schemas/svstore.TimestampDisplayOptions'
          title: timestamp
          x-stainless-terraform-configurability: optional
      required:
        - timestamp
      additionalProperties: false
    svstore.BoolDisplayOptions:
      type: object
      properties:
        style:
          $ref: '#/components/schemas/svstore.BoolDisplayOptions.Style'
          title: style
          x-stainless-terraform-configurability: optional
      title: BoolDisplayOptions
      additionalProperties: false
    svstore.NumberDisplayOptions:
      type: object
      properties:
        style:
          $ref: '#/components/schemas/svstore.NumberDisplayOptions.Style'
          title: style
          x-stainless-terraform-configurability: optional
        currencyCode:
          type:
            - string
            - 'null'
          title: currency_code
          description: ISO 4217 code ("USD", "EUR"). Required when style is CURRENCY.
          x-stainless-terraform-configurability: optional
        decimalPlaces:
          type:
            - integer
            - 'null'
          title: decimal_places
          format: int32
          description: |-
            Fixed digits after the decimal point. Unset renders the value's own
             precision, except CURRENCY which falls back to the code's minor unit.
          x-stainless-terraform-configurability: optional
        thousandsSeparator:
          type:
            - boolean
            - 'null'
          title: thousands_separator
          description: >-
            Unset means the default, which is grouping ON. Explicit presence
            rather
             than a plain bool: a plain bool reads as false when omitted, so a config
             written without the flag would silently drop grouping.
          x-stainless-terraform-configurability: optional
        prefix:
          type:
            - string
            - 'null'
          title: prefix
          description: |-
            Wrap the formatted number, for units the number itself can't carry
             ("GB", "seats", "/mo").
          x-stainless-terraform-configurability: optional
        suffix:
          type:
            - string
            - 'null'
          title: suffix
          x-stainless-terraform-configurability: optional
      title: NumberDisplayOptions
      additionalProperties: false
    svstore.TextDisplayOptions:
      type: object
      properties:
        autolink:
          type: boolean
          title: autolink
          description: Render bare URLs and email addresses as links.
          x-stainless-terraform-configurability: computed_optional
        monospace:
          type: boolean
          title: monospace
          description: Render in the monospace face, for IDs / serials / hashes.
          x-stainless-terraform-configurability: computed_optional
      title: TextDisplayOptions
      additionalProperties: false
    svstore.TimestampDisplayOptions:
      type: object
      properties:
        dateStyle:
          $ref: '#/components/schemas/svstore.TimestampDisplayOptions.DateStyle'
          title: date_style
          x-stainless-terraform-configurability: optional
        timeStyle:
          $ref: '#/components/schemas/svstore.TimestampDisplayOptions.TimeStyle'
          title: time_style
          description: >-
            Ignored when date_style is RELATIVE, which has no separate time
            part.
          x-stainless-terraform-configurability: optional
        timeZone:
          type:
            - string
            - 'null'
          title: time_zone
          description: >-
            IANA zone ("America/New_York"). Unset renders in the viewer's own
            zone.
             Pin it for fields whose values are only meaningful in one place, such as
             a warehouse's receiving timestamps.
          x-stainless-terraform-configurability: optional
      title: TimestampDisplayOptions
      additionalProperties: false
    svstore.BoolDisplayOptions.Style:
      type: string
      title: Style
      enum:
        - STYLE_UNSPECIFIED
        - TRUE_FALSE
        - YES_NO
        - CHECKBOX
    svstore.NumberDisplayOptions.Style:
      type: string
      title: Style
      enum:
        - STYLE_UNSPECIFIED
        - PLAIN
        - CURRENCY
        - PERCENT
    svstore.TimestampDisplayOptions.DateStyle:
      type: string
      title: DateStyle
      enum:
        - DATE_STYLE_UNSPECIFIED
        - NUMERIC_YMD
        - NUMERIC_MDY
        - NUMERIC_DMY
        - LOCALE_MEDIUM
        - LOCALE_LONG
        - RELATIVE
      description: |-
        NUMERIC_* orders are deliberately locale-independent: an operator who
         picks D/M/Y wants D/M/Y regardless of who is looking. LOCALE_* defer to
         the viewer's locale instead.
    svstore.TimestampDisplayOptions.TimeStyle:
      type: string
      title: TimeStyle
      enum:
        - TIME_STYLE_UNSPECIFIED
        - NONE
        - HOUR_MINUTE
        - HOUR_MINUTE_SECOND
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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