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

# Test a feed's mapping on a sample

> The app's test of a feed on a sample file: a dry run of its first 20 data rows that writes nothing. It returns the accounts each row matched, the field values, usage and object records it would write, each row's errors, and warnings, with the app's verdict (success). Test a saved feed (name) or one not saved yet (feed), on CSV text (csv) or a file Statisfy received (import_id). A test that finds bad rows is a 200 listing them.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/integrations/imports/test
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/imports/test:
    post:
      tags:
        - integrations
      summary: Test a feed's mapping on a sample
      description: >-
        The app's test of a feed on a sample file: a dry run of its first 20
        data rows that writes nothing. It returns the accounts each row matched,
        the field values, usage and object records it would write, each row's
        errors, and warnings, with the app's verdict (success). Test a saved
        feed (name) or one not saved yet (feed), on CSV text (csv) or a file
        Statisfy received (import_id). A test that finds bad rows is a 200
        listing them.
      operationId: integrations_test_mapping
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                csv:
                  anyOf:
                    - maxLength: 1048576
                      minLength: 1
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The sample as CSV text: the header row and at least the rows
                    to check
                  title: Csv
                feed:
                  anyOf:
                    - $ref: '#/components/schemas/FeedSettings'
                    - type: 'null'
                  default: null
                  description: Or a feed not saved yet, in the column shape
                import_id:
                  anyOf:
                    - maxLength: 64
                      minLength: 1
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    Or a file Statisfy received (integrations.list_imports): its
                    exact bytes
                  title: Import Id
                name:
                  anyOf:
                    - maxLength: 255
                      minLength: 1
                      type: string
                    - type: 'null'
                  default: null
                  description: A saved feed to test
                  title: Name
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingTest'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    FeedSettings:
      description: A feed in the column shape, as get_feed reads it.
      properties:
        allow_multiple_rows:
          default: false
          description: 'Usage: keep every row for one account and date'
          title: Allow Multiple Rows
          type: boolean
        clear_token:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: A cell holding only this text empties the field
          title: Clear Token
        columns:
          description: One entry per target
          items:
            $ref: '#/components/schemas/ColumnSetting'
          maxItems: 2000
          title: Columns
          type: array
        create_missing_people:
          default: false
          description: 'Person rows: create a person whose email isn''t found'
          title: Create Missing People
          type: boolean
        custom_object_append_only:
          default: false
          description: 'Objects: always add records, never update one'
          title: Custom Object Append Only
          type: boolean
        header_layout:
          anyOf:
            - $ref: '#/components/schemas/HeaderLayout'
            - type: 'null'
          default: null
          description: 'Where the column names are; unset: row 1'
        match:
          $ref: '#/components/schemas/FeedMatch'
        period:
          $ref: '#/components/schemas/PeriodSettings'
        row:
          default: account
          description: What one row of the file is
          enum:
            - account
            - person
          title: Row
          type: string
        source:
          $ref: '#/components/schemas/SourceSettings'
        validation_rules:
          anyOf:
            - $ref: '#/components/schemas/RulesSettings'
            - type: 'null'
          default: null
      required:
        - source
        - match
        - period
      title: FeedSettings
      type: object
    MappingTest:
      description: The app's test verdict on the same file (the wizard's Test step).
      properties:
        account_matches:
          items:
            $ref: '#/components/schemas/MappingTestAccount'
          title: Account Matches
          type: array
        custom_field_updates:
          items:
            $ref: '#/components/schemas/MappingTestFieldUpdate'
          title: Custom Field Updates
          type: array
        custom_object_records:
          items:
            $ref: '#/components/schemas/MappingTestObject'
          title: Custom Object Records
          type: array
        errors:
          description: Rows a real run fails (and skips, in strict mode)
          items:
            $ref: '#/components/schemas/MappingTestError'
          title: Errors
          type: array
        more_rows_in_file:
          description: The file has rows after the checked ones
          title: More Rows In File
          type: boolean
        product_usage_records:
          items:
            $ref: '#/components/schemas/MappingTestUsage'
          title: Product Usage Records
          type: array
        rows_validated:
          title: Rows Validated
          type: integer
        success:
          description: The rows checked would import; warnings may still apply
          title: Success
          type: boolean
        summary_stats:
          $ref: '#/components/schemas/MappingTestSummary'
        warnings:
          description: Bad cells, fields the feed won't write, and other notes
          items:
            type: string
          title: Warnings
          type: array
      required:
        - success
        - rows_validated
        - errors
        - warnings
        - account_matches
        - custom_field_updates
        - product_usage_records
        - custom_object_records
        - summary_stats
        - more_rows_in_file
      title: MappingTest
      type: object
    ColumnSetting:
      properties:
        column:
          description: The column's name in the file, as its header row spells it
          maxLength: 500
          minLength: 1
          title: Column
          type: string
        date_format:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: 'For a date field: one of the rules'' date_formats'
          title: Date Format
        target:
          description: >-
            Where the column goes: account.<field> (a standard field: arr,
            domain, name, renewal_date, type), account.fields.<key>,
            usage.<product id>.<dimension key>, objects.<object
            key>.external_id, objects.<object key>.<field key>, person.<field>
            or person.fields.<key>
          maxLength: 600
          minLength: 1
          title: Target
          type: string
        transform:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Leave unset; the app sets it
          title: Transform
      required:
        - column
        - target
      title: ColumnSetting
      type: object
    HeaderLayout:
      description: |-
        Where the column names are in a file.

        Row numbers are 1-based raw rows of the file. ``HeaderLayout()`` is
        today's layout: the names are in row 1 and there is no group row.
      properties:
        group_row:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: null
          description: 1-based raw row of the group names above the column names, or None
          title: Group Row
        header_row:
          default: 1
          description: 1-based raw row of the column names
          maximum: 20
          minimum: 1
          title: Header Row
          type: integer
      title: HeaderLayout
      type: object
    FeedMatch:
      properties:
        column:
          description: The column that names each row's account
          title: Column
          type: string
        field:
          description: >-
            The account field it matches: crm_account_id, domain, name or a
            custom field key
          title: Field
          type: string
      required:
        - column
        - field
      title: FeedMatch
      type: object
    PeriodSettings:
      properties:
        date_column:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            A column dating each row's usage. Unset: a file's usage is filed
            under the period before the one it arrived in
          title: Date Column
        snapshot:
          description: The period product usage is kept by
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - yearly
            - single
          title: Snapshot
          type: string
        week_start:
          default: monday
          enum:
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
            - sunday
          title: Week Start
          type: string
      required:
        - snapshot
      title: PeriodSettings
      type: object
    SourceSettings:
      properties:
        attachment_filter:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'Email: a pattern that picks the file when an email carries several'
          title: Attachment Filter
        bucket:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'S3: the bucket'
          title: Bucket
        connection:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'S3: an AWS S3 connection made in the app'
          title: Connection
        kind:
          description: 'email: files sent to the feed''s address; s3: a bucket polled'
          enum:
            - email
            - s3
          title: Kind
          type: string
        prefix:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'S3: only keys under this'
          title: Prefix
        region:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'S3: the bucket''s region; default us-east-1'
          title: Region
        subject_filter:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          default: null
          description: 'Email: only emails whose subject holds this'
          title: Subject Filter
      required:
        - kind
      title: SourceSettings
      type: object
    RulesSettings:
      properties:
        allow_partial_success:
          default: true
          description: Import the good rows when some fail
          title: Allow Partial Success
          type: boolean
        required_columns:
          description: Columns a file must have
          items:
            maxLength: 500
            minLength: 1
            type: string
          title: Required Columns
          type: array
        skip_on_error:
          default: false
          description: 'Stop at the first bad row: write nothing'
          title: Skip On Error
          type: boolean
      title: RulesSettings
      type: object
    MappingTestAccount:
      properties:
        account_id:
          description: The account it matched; empty when none
          title: Account Id
          type: string
        account_name:
          title: Account Name
          type: string
        csv_identifier:
          description: The identifier cell
          title: Csv Identifier
          type: string
        matched:
          title: Matched
          type: boolean
        row_number:
          title: Row Number
          type: integer
      required:
        - csv_identifier
        - account_id
        - account_name
        - matched
        - row_number
      title: MappingTestAccount
      type: object
    MappingTestFieldUpdate:
      properties:
        account_id:
          title: Account Id
          type: string
        account_name:
          title: Account Name
          type: string
        action:
          enum:
            - set
            - clear
          title: Action
          type: string
        field_key:
          title: Field Key
          type: string
        field_label:
          title: Field Label
          type: string
        new_value:
          title: New Value
        row_number:
          title: Row Number
          type: integer
      required:
        - account_id
        - account_name
        - field_key
        - field_label
        - action
        - new_value
        - row_number
      title: MappingTestFieldUpdate
      type: object
    MappingTestObject:
      properties:
        account_id:
          title: Account Id
          type: string
        account_name:
          title: Account Name
          type: string
        custom_object_name:
          title: Custom Object Name
          type: string
        external_id:
          title: External Id
          type: string
        field_values:
          additionalProperties: true
          title: Field Values
          type: object
        row_number:
          title: Row Number
          type: integer
      required:
        - account_id
        - account_name
        - custom_object_name
        - external_id
        - field_values
        - row_number
      title: MappingTestObject
      type: object
    MappingTestError:
      properties:
        column:
          anyOf:
            - type: string
            - type: 'null'
          title: Column
        error_type:
          title: Error Type
          type: string
        message:
          title: Message
          type: string
        row_number:
          description: 'The file''s row (0 or less: the whole file)'
          title: Row Number
          type: integer
      required:
        - row_number
        - column
        - error_type
        - message
      title: MappingTestError
      type: object
    MappingTestUsage:
      properties:
        account_id:
          title: Account Id
          type: string
        account_name:
          title: Account Name
          type: string
        dimension_key:
          title: Dimension Key
          type: string
        dimension_name:
          title: Dimension Name
          type: string
        product_name:
          title: Product Name
          type: string
        row_number:
          title: Row Number
          type: integer
        snapshot_date:
          description: The period's date the usage is filed under
          title: Snapshot Date
          type: string
        snapshot_period:
          title: Snapshot Period
          type: string
        value:
          title: Value
        value_type:
          title: Value Type
          type: string
      required:
        - account_id
        - account_name
        - product_name
        - dimension_key
        - dimension_name
        - value
        - value_type
        - snapshot_date
        - snapshot_period
        - row_number
      title: MappingTestUsage
      type: object
    MappingTestSummary:
      properties:
        accounts_matched:
          title: Accounts Matched
          type: integer
        accounts_not_found:
          title: Accounts Not Found
          type: integer
        custom_field_clears:
          title: Custom Field Clears
          type: integer
        custom_field_updates:
          title: Custom Field Updates
          type: integer
        custom_object_records:
          title: Custom Object Records
          type: integer
        people_field_updates:
          default: 0
          title: People Field Updates
          type: integer
        people_matched:
          default: 0
          description: Person rows only
          title: People Matched
          type: integer
        people_not_found:
          default: 0
          title: People Not Found
          type: integer
        people_to_create:
          default: 0
          title: People To Create
          type: integer
        product_usage_records:
          title: Product Usage Records
          type: integer
        unique_accounts:
          title: Unique Accounts
          type: integer
      required:
        - unique_accounts
        - accounts_matched
        - accounts_not_found
        - custom_field_updates
        - custom_field_clears
        - product_usage_records
        - custom_object_records
      title: MappingTestSummary
      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.