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

# Save a new Pendo query

> Adds a query to the Pendo config (201). `query` is the Pendo aggregation JSON as text: check it first with POST /v1/integrations/pendo/query/validate. Every mapped field or metric must already exist: create them with /v1/fields and /v1/products first. A people query takes its internal domains from the workspace's own when you leave them out. Saving locks each mapped field: the integration writes it, so it is read-only in the app. A save runs the app's Pendo checks first, and a refusal is a 422 with the app's text: a query that is not valid Pendo aggregation JSON, a query that uses {PENDO_ACCOUNT_ID_FIELD} while no account ID field is set, group_by_columns, order_by_columns or limit (they do not apply to Pendo), a survey ID with a character other than a letter, digit, - or _, a custom field match that is not a text custom field of accounts. A 409 means the config changed since you read it (or `expected_version` is not the live one): read it again.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/integrations/pendo/queries
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/integrations/pendo/queries:
    post:
      tags:
        - integrations
      summary: Save a new Pendo query
      description: >-
        Adds a query to the Pendo config (201). `query` is the Pendo aggregation
        JSON as text: check it first with POST
        /v1/integrations/pendo/query/validate. Every mapped field or metric must
        already exist: create them with /v1/fields and /v1/products first. A
        people query takes its internal domains from the workspace's own when
        you leave them out. Saving locks each mapped field: the integration
        writes it, so it is read-only in the app. A save runs the app's Pendo
        checks first, and a refusal is a 422 with the app's text: a query that
        is not valid Pendo aggregation JSON, a query that uses
        {PENDO_ACCOUNT_ID_FIELD} while no account ID field is set,
        group_by_columns, order_by_columns or limit (they do not apply to
        Pendo), a survey ID with a character other than a letter, digit, - or _,
        a custom field match that is not a text custom field of accounts. A 409
        means the config changed since you read it (or `expected_version` is not
        the live one): read it again.
      operationId: integrations_pendo_create_query
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                account_resolver:
                  anyOf:
                    - $ref: '#/components/schemas/AccountResolverConfig'
                    - type: 'null'
                  default: null
                  description: >-
                    How a row finds its account. Required, except for a people
                    query that creates no people
                custom_field_mappings:
                  anyOf:
                    - items:
                        $ref: '#/components/schemas/CustomFieldMappingConfig'
                      type: array
                    - type: 'null'
                  default: null
                  description: >-
                    custom_field queries: column -> field. Each field must
                    already exist (/v1/fields)
                  title: Custom Field Mappings
                custom_object_config:
                  anyOf:
                    - $ref: '#/components/schemas/CustomObjectConfig'
                    - type: 'null'
                  default: null
                  description: custom_object queries
                entity_type:
                  default: account
                  description: >-
                    custom_field only: write account fields, or people (contact)
                    fields
                  enum:
                    - account
                    - people
                  title: Entity Type
                  type: string
                expected_version:
                  anyOf:
                    - description: >-
                        The config `version` you read. Sent: a change against a
                        version that is no longer live is a 409 and writes
                        nothing (0 = the config was never saved). Left out, the
                        change always lands
                      minimum: 0
                      type: integer
                    - type: 'null'
                  default: null
                  title: Expected Version
                is_active:
                  default: true
                  description: An inactive query is kept but not run
                  title: Is Active
                  type: boolean
                name:
                  maxLength: 200
                  minLength: 1
                  title: Name
                  type: string
                period:
                  anyOf:
                    - enum:
                        - HOURLY
                        - TWO_HOURS
                        - FOUR_HOURS
                        - SIX_HOURS
                        - TWELVE_HOURS
                        - DAILY
                        - WEEKLY
                        - MONTHLY
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The window each run covers; null follows the schedule
                    (weekly by default). product_usage takes DAILY, WEEKLY or
                    MONTHLY only
                  title: Period
                person_resolver:
                  anyOf:
                    - $ref: '#/components/schemas/PersonResolverConfig'
                    - type: 'null'
                  default: null
                  description: >-
                    people queries: how a row finds its person. The internal
                    domains default to the workspace's own
                product_usage_mappings:
                  anyOf:
                    - items:
                        $ref: '#/components/schemas/ProductUsageMappingConfig'
                      type: array
                    - type: 'null'
                  default: null
                  description: >-
                    product_usage queries: column -> metric. Each metric must
                    already exist (/v1/products)
                  title: Product Usage Mappings
                query:
                  description: >-
                    The Pendo aggregation JSON, as text. A request body with a
                    `request.pipeline`. It may use {START_DATE_MS},
                    {END_DATE_MS} and {PENDO_ACCOUNT_ID_FIELD}, which each run
                    fills in
                  maxLength: 100000
                  minLength: 1
                  title: Query
                  type: string
                query_type:
                  description: >-
                    custom_field writes field values; product_usage writes usage
                    metrics; custom_object writes records
                  enum:
                    - custom_field
                    - product_usage
                    - custom_object
                  title: Query Type
                  type: string
                transformers:
                  anyOf:
                    - items:
                        $ref: '#/components/schemas/ColumnTransformerConfig'
                      type: array
                    - type: 'null'
                  default: null
                  description: >-
                    Per-column value pipelines, applied after the account lookup
                    and before writing
                  title: Transformers
              required:
                - name
                - query_type
                - query
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendoQuery'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    AccountResolverConfig:
      description: >-
        How to map record rows to internal Statisfy account IDs.


        Used by warehouse integrations (postgres/redshift/bigquery/snowflake)
        and

        JIRA. The schema is integration-agnostic; resolver types are dispatched
        by

        the integration's hydrator.
      properties:
        abbreviations:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          default: null
          description: >-
            Map of summary prefix abbreviation to canonical customer name
            (abbreviation_map)
          title: Abbreviations
        column:
          description: Source column in record containing the identifier
          title: Column
          type: string
        custom_field_key:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Custom field key for custom_field/custom_field_bulk resolver types
          title: Custom Field Key
        cutoff:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: >-
            Fuzzy matching cutoff for account_name / parent_epic_summary /
            jira_field (name target) / payload_field (name target) resolvers
            (0.0-1.0). Default 0.5; tenants that need stricter matching (e.g.
            Eightfold's 0.9) set explicitly.
          title: Cutoff
        exclude_keywords:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: >-
            Parent-epic summaries equal (after strip) to any of these strings
            are skipped (parent_epic_summary). Exact-match semantics — list the
            full summary text, not a substring.
          title: Exclude Keywords
        field_to_parse:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Record key to parse for the abbreviation prefix (abbreviation_map;
            default 'summary')
          title: Field To Parse
        match_mode:
          anyOf:
            - enum:
                - exact
                - similar
              type: string
            - type: 'null'
          default: null
          description: >-
            How account_name and the name target of payload_field /
            rocketlane_field / jira_field / linear_field compare names. 'exact'
            matches the whole name, ignoring case. It compares the stored name
            as is, so a stored name with an edge space does not match. 'similar'
            or unset uses the fuzzy match with `cutoff`.
          title: Match Mode
        type:
          enum:
            - statisfy_account_id
            - crm_account_id
            - organization_id
            - email_domain
            - custom_field
            - custom_field_bulk
            - account_name
            - parent_epic_summary
            - abbreviation_map
            - jira_field
            - rocketlane_field
            - linear_field
            - payload_field
          title: Type
          type: string
        value_transform:
          anyOf:
            - $ref: '#/components/schemas/ValueTransformConfig'
            - type: 'null'
          default: null
          description: >-
            Optional pre-lookup transforms on the extracted value. Honored by
            the jira_field resolver to express Milestone- and SproutsAI-style
            value shaping (prefix stripping, sentinel skipping, first-token
            extraction).
      required:
        - type
        - column
      title: AccountResolverConfig
      type: object
    CustomFieldMappingConfig:
      description: Maps a query result column to a Statisfy custom field.
      properties:
        field_type:
          enum:
            - int
            - str
            - float
            - bool
            - date
            - datetime
            - json
            - str_list
          title: Field Type
          type: string
        key:
          description: Custom field key in Statisfy (e.g. 'invites_accepted__c_')
          title: Key
          type: string
        source_column:
          description: Column name in query results
          title: Source Column
          type: string
      required:
        - key
        - field_type
        - source_column
      title: CustomFieldMappingConfig
      type: object
    CustomObjectConfig:
      description: Configuration for custom object ingestion from a query.
      properties:
        external_id_column:
          description: Column for unique record ID
          title: External Id Column
          type: string
        field_mappings:
          items:
            $ref: '#/components/schemas/CustomObjectFieldMappingConfig'
          title: Field Mappings
          type: array
        key:
          description: Object key (e.g. 'Frameworks')
          title: Key
          type: string
        name:
          description: Display name (e.g. 'Frameworks')
          title: Name
          type: string
      required:
        - name
        - key
        - external_id_column
        - field_mappings
      title: CustomObjectConfig
      type: object
    PersonResolverConfig:
      description: >-
        How to map query result rows to internal Statisfy person/contact IDs.


        Used only for queries with entity_type='people'. Maps a row's email
        column

        to a person; new people are upserted via process_person when not found.

        The account_resolver on the same query attaches the new person to an

        account (cust_id).
      properties:
        alias_domains:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: Additional tenant-owned domains (multi-domain tenants).
          title: Alias Domains
        create_missing_people:
          default: true
          description: >-
            If False, only people that already exist (matched by email) get
            values. No person is created, and the account resolver is not
            needed.
          title: Create Missing People
          type: boolean
        email_column:
          description: Source column in query results containing the email
          title: Email Column
          type: string
        first_name_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: First Name Column
        last_name_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Last Name Column
        name_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Optional column with full name
          title: Name Column
        tenant_domain:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            If set, emails matching this domain are classified as INTERNAL
            (person_pb2.PersonType.INTERNAL); otherwise EXTERNAL.
          title: Tenant Domain
      required:
        - email_column
      title: PersonResolverConfig
      type: object
    ProductUsageMappingConfig:
      description: Maps a query result column to a product usage metric.
      properties:
        metric_name:
          description: Metric key in product_usage_dimensions
          title: Metric Name
          type: string
        source_column:
          description: Column name in query results
          title: Source Column
          type: string
        value_type:
          default: int
          enum:
            - int
            - float
            - str
            - bool
            - date
            - percent
            - percent_ratio
          title: Value Type
          type: string
      required:
        - metric_name
        - source_column
      title: ProductUsageMappingConfig
      type: object
    ColumnTransformerConfig:
      description: |-
        A pipeline of transform steps applied to one column on each query row.

        Steps run in declared order. The first step that returns None ends the
        pipeline and the column is written as None. If `target_column` is unset,
        the result is written back to `source_column`.
      properties:
        source_column:
          description: Column to read the raw value from
          title: Source Column
          type: string
        steps:
          description: Pipeline of transform steps applied left-to-right.
          items:
            discriminator:
              mapping:
                lookup: '#/components/schemas/LookupStep'
                regex_extract: '#/components/schemas/RegexExtractStep'
                skip_if_contains: '#/components/schemas/SkipIfContainsStep'
                skip_if_equals: '#/components/schemas/SkipIfEqualsStep'
                split_first_token: '#/components/schemas/SplitFirstTokenStep'
                strip_prefix: '#/components/schemas/StripPrefixStep'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/LookupStep'
              - $ref: '#/components/schemas/StripPrefixStep'
              - $ref: '#/components/schemas/SplitFirstTokenStep'
              - $ref: '#/components/schemas/RegexExtractStep'
              - $ref: '#/components/schemas/SkipIfEqualsStep'
              - $ref: '#/components/schemas/SkipIfContainsStep'
          title: Steps
          type: array
        target_column:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Column to write the result to (defaults to source_column).
          title: Target Column
      required:
        - source_column
      title: ColumnTransformerConfig
      type: object
    PendoQuery:
      description: >-
        A saved Pendo query as stored. Its resolver, mapping and transformer
        objects have the same shapes as in

        a SQL warehouse query.
      properties:
        account_resolver:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: How a row finds its account
          title: Account Resolver
        custom_field_mappings:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: 'custom_field queries: column to field'
          title: Custom Field Mappings
        custom_object_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: custom_object queries
          title: Custom Object Config
        entity_type:
          description: 'custom_field only: account fields or people fields'
          enum:
            - account
            - people
          title: Entity Type
          type: string
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Stable id. null only on a query saved before ids existed: any save
            of the config gives it one
          title: Id
        is_active:
          description: An inactive query is kept but not run
          title: Is Active
          type: boolean
        name:
          title: Name
          type: string
        period:
          anyOf:
            - enum:
                - HOURLY
                - TWO_HOURS
                - FOUR_HOURS
                - SIX_HOURS
                - TWELVE_HOURS
                - DAILY
                - WEEKLY
                - MONTHLY
              type: string
            - type: 'null'
          description: >-
            The window each run covers. null follows the schedule (weekly by
            default)
          title: Period
        person_resolver:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: 'people queries: how a row finds its person'
          title: Person Resolver
        product_usage_mappings:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: 'product_usage queries: column to metric'
          title: Product Usage Mappings
        query:
          description: >-
            The Pendo aggregation JSON, as text. A request body with a
            `request.pipeline`. It may use {START_DATE_MS}, {END_DATE_MS} and
            {PENDO_ACCOUNT_ID_FIELD}, which each run fills in
          title: Query
          type: string
        query_type:
          description: >-
            custom_field writes field values; product_usage writes usage
            metrics; custom_object writes records
          enum:
            - custom_field
            - product_usage
            - custom_object
          title: Query Type
          type: string
        transformers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: Per-column value pipelines
          title: Transformers
        version:
          description: 'The config''s version: send it as `expected_version` with a change'
          title: Version
          type: integer
      required:
        - id
        - version
        - name
        - query_type
        - query
        - entity_type
        - period
        - account_resolver
        - person_resolver
        - custom_field_mappings
        - product_usage_mappings
        - custom_object_config
        - transformers
        - is_active
      title: PendoQuery
      type: object
    ValueTransformConfig:
      description: >-
        Pre-lookup transforms applied to a raw field value before resolver
        matching.


        Captures shapes the legacy per-tenant providers expressed in code: skip

        sentinel values (Milestone's "Milestone" literal), strip prefixes

        (Milestone's "CUST-" prefix), split on a separator and take the first

        token (SproutsAI's `summary.split("|")[0]`, Milestone's space- or

        underscore-split). All fields are optional and applied left-to-right in

        the order listed below. If any step yields an empty string the resolver

        treats the field as missing.


        Currently honored by `JiraFieldAccountResolver`. Future resolvers can
        opt

        in by reading `value_transform` and applying `apply_value_transform()`.
      properties:
        regex_extract:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Python regex pattern; if it matches, replace the value with the
            first capture group. Applied last so it can post-process the output
            of the other transforms.
          title: Regex Extract
        skip_if_contains:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: If the raw value contains this substring, return None / skip lookup.
          title: Skip If Contains
        skip_if_equals:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            If the raw value equals this string (after strip), return None /
            skip lookup.
          title: Skip If Equals
        split_first_token:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Split the value on this separator and keep the first non-empty
            token. E.g. '|' for SproutsAI's 'Acme | INC-123' summary shape; ' '
            or '_' for Milestone.
          title: Split First Token
        strip_prefix:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: If the value starts with this prefix, remove it before lookup.
          title: Strip Prefix
      title: ValueTransformConfig
      type: object
    CustomObjectFieldMappingConfig:
      description: Maps a query result column to a custom object field.
      properties:
        field_label:
          title: Field Label
          type: string
        field_type:
          enum:
            - int
            - str
            - float
            - bool
            - date
            - datetime
          title: Field Type
          type: string
        key:
          title: Key
          type: string
        source_column:
          title: Source Column
          type: string
      required:
        - key
        - field_type
        - source_column
        - field_label
      title: CustomObjectFieldMappingConfig
      type: object
    LookupStep:
      description: |-
        Dictionary lookup. Unmapped values pass through unchanged by default;
        set `keep_unmapped=False` to drop them (filter behavior).
      properties:
        delimiter:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            If set, value is split on this delimiter, each token mapped, then
            rejoined.
          title: Delimiter
        keep_unmapped:
          default: true
          description: >-
            When True (default), values not in `mapping` pass through unchanged.
            When False, unmapped values are dropped (filter).
          title: Keep Unmapped
          type: boolean
        mapping:
          additionalProperties:
            type: string
          description: Raw value -> display value mapping
          title: Mapping
          type: object
        type:
          const: lookup
          default: lookup
          title: Type
          type: string
      required:
        - mapping
      title: LookupStep
      type: object
    RegexExtractStep:
      description: |-
        Apply regex, replace value with the first capture group. Drops the
        value if the pattern doesn't match or has no capture group.
      properties:
        pattern:
          maxLength: 256
          minLength: 1
          title: Pattern
          type: string
        type:
          const: regex_extract
          default: regex_extract
          title: Type
          type: string
      required:
        - pattern
      title: RegexExtractStep
      type: object
    SkipIfContainsStep:
      description: Drop the value (return None) if it contains the given substring.
      properties:
        substring:
          minLength: 1
          title: Substring
          type: string
        type:
          const: skip_if_contains
          default: skip_if_contains
          title: Type
          type: string
      required:
        - substring
      title: SkipIfContainsStep
      type: object
    SkipIfEqualsStep:
      description: Drop the value (return None) if it equals the given string.
      properties:
        type:
          const: skip_if_equals
          default: skip_if_equals
          title: Type
          type: string
        value:
          title: Value
          type: string
      required:
        - value
      title: SkipIfEqualsStep
      type: object
    SplitFirstTokenStep:
      description: |-
        Split on delimiter, keep the first non-empty token (trimmed). Drops the
        value if no non-empty token is produced.
      properties:
        delimiter:
          minLength: 1
          title: Delimiter
          type: string
        type:
          const: split_first_token
          default: split_first_token
          title: Type
          type: string
      required:
        - delimiter
      title: SplitFirstTokenStep
      type: object
    StripPrefixStep:
      description: Remove leading prefix if present; pass through unchanged if not.
      properties:
        prefix:
          minLength: 1
          title: Prefix
          type: string
        type:
          const: strip_prefix
          default: strip_prefix
          title: Type
          type: string
      required:
        - prefix
      title: StripPrefixStep
      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.