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

# Create a custom field definition on an object

> Creates a custom field on account, contact, opportunity, project, task or user. Provide a display name (letters, numbers, spaces, hyphens, underscores) and a type (text, number, date, boolean, float, url, currency, datetime, text_list, lookup, ...). Picklists take options (+ optional labels); currency takes currency_code; float and percent take decimal_places; lookup requires lookup_object. An account, a contact or an opportunity field takes a formula, which the app's validator checks (a formula it refuses is a 400 with its messages). Pill, lifecycle and object fields are not supported. A task field is on every task in a project, and on activity tasks outside one. A project field can be written on any project: the first value written to a project attaches the field to it. A value written to a project or a project's task shows the field there in the app (internal for sharing), unless someone removed it from that project. A field's key comes from its name and is unique across all objects' custom fields: a taken key is a 409. Returns the new field's definition; use its key immediately in reads, filters, and value writes. Users filter on standard fields only, so a user field's key is not a filter. On a custom object (object=<its key>), a field is keyed `<object>__<field>`, its field part made from the name as the app's Object Manager makes it; its types are text, textarea, text_list, number, float, percent, percent_ratio, currency, boolean, date, datetime, url and pill (a picklist, which takes options). An object a warehouse or another system fills takes no new field.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/fields
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:
    post:
      tags:
        - fields
      summary: Create a custom field definition on an object
      description: >-
        Creates a custom field on account, contact, opportunity, project, task
        or user. Provide a display name (letters, numbers, spaces, hyphens,
        underscores) and a type (text, number, date, boolean, float, url,
        currency, datetime, text_list, lookup, ...). Picklists take options (+
        optional labels); currency takes currency_code; float and percent take
        decimal_places; lookup requires lookup_object. An account, a contact or
        an opportunity field takes a formula, which the app's validator checks
        (a formula it refuses is a 400 with its messages). Pill, lifecycle and
        object fields are not supported. A task field is on every task in a
        project, and on activity tasks outside one. A project field can be
        written on any project: the first value written to a project attaches
        the field to it. A value written to a project or a project's task shows
        the field there in the app (internal for sharing), unless someone
        removed it from that project. A field's key comes from its name and is
        unique across all objects' custom fields: a taken key is a 409. Returns
        the new field's definition; use its key immediately in reads, filters,
        and value writes. Users filter on standard fields only, so a user
        field's key is not a filter. On a custom object (object=<its key>), a
        field is keyed `<object>__<field>`, its field part made from the name as
        the app's Object Manager makes it; its types are text, textarea,
        text_list, number, float, percent, percent_ratio, currency, boolean,
        date, datetime, url and pill (a picklist, which takes options). An
        object a warehouse or another system fills takes no new field.
      operationId: fields_create
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                currency_code:
                  anyOf:
                    - type: string
                    - type: 'null'
                  default: null
                  title: Currency Code
                decimal_places:
                  anyOf:
                    - maximum: 15
                      minimum: 0
                      type: integer
                    - type: 'null'
                  default: null
                  title: Decimal Places
                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: >-
                    Makes the field a formula, on account, contact or
                    opportunity. Its value is computed: POST
                    /v1/fields/{field_key}/recompute computes it now, and a job
                    computes it every 4 hours.
                  title: Formula
                lookup_object:
                  anyOf:
                    - type: string
                    - type: 'null'
                  default: null
                  description: 'For lookup fields: the object the field points at'
                  title: Lookup Object
                name:
                  maxLength: 255
                  minLength: 1
                  pattern: ^[A-Za-z0-9 _-]*[A-Za-z0-9][A-Za-z0-9 _-]*$
                  title: Name
                  type: string
                object:
                  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)
                  title: Object
                  type: string
                option_labels:
                  anyOf:
                    - additionalProperties:
                        type: string
                      type: object
                    - type: 'null'
                  default: null
                  title: Option Labels
                options:
                  anyOf:
                    - items:
                        type: string
                      type: array
                    - type: 'null'
                  default: null
                  title: Options
                project_templates:
                  anyOf:
                    - items:
                        type: string
                      maxItems: 100
                      type: array
                    - type: 'null'
                  default: null
                  description: >-
                    For a project or a task field: the project templates it
                    joins (needs projects:update too)
                  title: Project Templates
                type:
                  description: >-
                    Field type; one of: boolean, currency, date, datetime,
                    float, json, lifecycle_stage, lookup, lookup_list, number,
                    object, percent, percent_ratio, pill, text, text_list,
                    textarea, url
                  title: Type
                  type: string
              required:
                - object
                - name
                - type
              type: object
        required: true
      responses:
        '201':
          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.