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

# Preview Entity Type Field Formula

> Check a formula for an entity type field without saving it. Returns compile_error when the formula is invalid for the field's data type, and the field IDs it reads. Pass entity_id to also evaluate it on that entity: value is the result, or runtime_error says why it failed. Set default_formula to check it as a create-time default. Nothing is written. Evaluating on an entity requires access to every field the formula reads there. 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:read` |
| Team-scoped API key | `entities:read` |
| 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.

* **Check a field's formula in a team's database:** The permission is checked on the team that owns the field's database. Previewing on an entity also requires access to that entity and to every field the formula reads on it.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml post /v2/entity-type-fields/{id}/formula/preview
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/preview:
    post:
      tags:
        - Entity Type API
      summary: Preview Entity Type Field Formula
      description: >-
        Check a formula for an entity type field without saving it. Returns
        compile_error when the formula is invalid for the field's data type, and
        the field IDs it reads. Pass entity_id to also evaluate it on that
        entity: value is the result, or runtime_error says why it failed. Set
        default_formula to check it as a create-time default. Nothing is
        written. Evaluating on an entity requires access to every field the
        formula reads there. 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.PreviewEntityTypeFieldFormula
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: id
            description: >-
              The ID of the output entity type field. Its data type is the type
              the
               formula must produce.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                formula:
                  type: string
                  title: formula
                  description: The formula to check.
                defaultFormula:
                  type: boolean
                  title: default_formula
                  description: >-
                    Check the formula as a create-time default instead of a
                    computed
                     formula. Defaults may read only entered fields.
                entityId:
                  type:
                    - string
                    - 'null'
                  title: entity_id
                  description: >-
                    Also evaluate the formula against this entity. Omit to
                    compile only.
              title: PreviewEntityTypeFieldFormulaRequest
              additionalProperties: false
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/svstore.publicapi.PreviewEntityTypeFieldFormulaResponse
      security:
        - BearerAuth: []
components:
  schemas:
    svstore.publicapi.PreviewEntityTypeFieldFormulaResponse:
      type: object
      properties:
        compileError:
          type:
            - string
            - 'null'
          title: compile_error
          description: Why the formula does not compile. Unset when it compiles.
          x-stainless-terraform-configurability: optional
        runtimeError:
          type:
            - string
            - 'null'
          title: runtime_error
          description: |-
            Why evaluating on entity_id failed. A saved formula leaves the field
             empty on such a record.
          x-stainless-terraform-configurability: optional
        value:
          $ref: '#/components/schemas/google.protobuf.Value'
          title: value
          description: |-
            The result on entity_id: a string, number or bool, an RFC 3339
             timestamp, or the option ID for an ENUM output. Unset when the result
             is empty, evaluation failed, or entity_id was omitted.
          x-stainless-terraform-configurability: optional
        readFieldIds:
          type: array
          items:
            type: string
          title: read_field_ids
          description: The entity type field IDs on this type the formula reads.
          x-stainless-terraform-configurability: optional
      title: PreviewEntityTypeFieldFormulaResponse
      additionalProperties: false
    google.protobuf.Value:
      oneOf:
        - type: 'null'
        - type: number
        - type: string
        - type: boolean
        - type: array
        - type: object
          additionalProperties: true
      description: |-
        `Value` represents a dynamically typed value which can be either
         null, a number, a string, a boolean, a recursive struct value, or a
         list of values. A producer of value is expected to set one of these
         variants. Absence of any variant indicates an error.

         The JSON representation for `Value` is JSON value.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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