> ## 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 file import feed

> A new recurring file feed (Periodic Data Import), switched off until update_feed switches it on: an email feed holds each file it receives (status held) and an S3 feed isn't polled; run_feed imports one file meanwhile. A feed reads as get_feed shows it: source (email, or s3 on an AWS S3 connection made in the app), row (account or person), match (the column that names each row's account, and the account field it matches), period, and columns, one entry per mapped column naming its target (see integrations.import_targets). The save runs the app's checks: a refused column comes back as a 422 naming each column and why. Saving locks each mapped field, so it is read-only in the app. Test the mapping (integrations.test_mapping) before switching the feed on.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/integrations/imports/feeds
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/feeds:
    post:
      tags:
        - integrations
      summary: Create a file import feed
      description: >-
        A new recurring file feed (Periodic Data Import), switched off until
        update_feed switches it on: an email feed holds each file it receives
        (status held) and an S3 feed isn't polled; run_feed imports one file
        meanwhile. A feed reads as get_feed shows it: source (email, or s3 on an
        AWS S3 connection made in the app), row (account or person), match (the
        column that names each row's account, and the account field it matches),
        period, and columns, one entry per mapped column naming its target (see
        integrations.import_targets). The save runs the app's checks: a refused
        column comes back as a 422 naming each column and why. Saving locks each
        mapped field, so it is read-only in the app. Test the mapping
        (integrations.test_mapping) before switching the feed on.
      operationId: integrations_create_feed
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              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'
                name:
                  description: >-
                    Letters, digits and underscores; unique (also by case), and
                    fixed once saved
                  maxLength: 255
                  minLength: 1
                  pattern: ^[a-zA-Z0-9_]+$
                  title: Name
                  type: string
                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
                - name
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportFeed'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    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
    ImportFeed:
      properties:
        active:
          description: >-
            False: an email that arrives is held for the feed (status held), not
            imported; an S3 feed isn't polled
          title: Active
          type: boolean
        allow_multiple_rows:
          description: 'Usage: keep every row, even several for one account and date'
          title: Allow Multiple Rows
          type: boolean
        clear_token:
          anyOf:
            - type: string
            - type: 'null'
          description: 'A cell holding only this text empties the field; null: off'
          title: Clear Token
        columns:
          description: Every mapped column, one entry per target
          items:
            $ref: '#/components/schemas/ImportColumn'
          title: Columns
          type: array
        create_missing_people:
          description: 'Person rows: create a person whose email isn''t found'
          title: Create Missing People
          type: boolean
        created_at:
          format: date-time
          title: Created At
          type: string
        custom_object_append_only:
          description: 'Objects: always add records, never update one'
          title: Custom Object Append Only
          type: boolean
        header_layout:
          anyOf:
            - $ref: '#/components/schemas/HeaderRows'
            - type: 'null'
          description: 'Where the column names are; null: row 1'
        match:
          $ref: '#/components/schemas/FeedMatch'
        name:
          description: Unique; an email feed's address carries it
          title: Name
          type: string
        period:
          $ref: '#/components/schemas/FeedPeriod'
        row:
          description: What one row of the file is
          enum:
            - account
            - person
          title: Row
          type: string
        source:
          $ref: '#/components/schemas/FeedSource'
        updated_at:
          format: date-time
          title: Updated At
          type: string
        validation_rules:
          $ref: '#/components/schemas/ValidationRules'
        version:
          description: Send it as expected_version with a change or a delete
          format: date-time
          title: Version
          type: string
      required:
        - name
        - active
        - source
        - row
        - match
        - period
        - columns
        - header_layout
        - clear_token
        - create_missing_people
        - allow_multiple_rows
        - custom_object_append_only
        - validation_rules
        - created_at
        - updated_at
        - version
      title: ImportFeed
      type: object
    ImportColumn:
      properties:
        column:
          description: The column's name in the file, as its header row spells it
          title: Column
          type: string
        date_format:
          anyOf:
            - type: string
            - type: 'null'
          description: 'For a date field: how the file writes dates'
          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>
          title: Target
          type: string
        transform:
          anyOf:
            - type: string
            - type: 'null'
          description: Set in the app only; account.fields targets
          title: Transform
      required:
        - column
        - target
      title: ImportColumn
      type: object
    HeaderRows:
      description: >-
        Where a file's column names are (a request takes the same fields as
        ``header_layout``).
      properties:
        group_row:
          anyOf:
            - type: integer
            - type: 'null'
          description: 1-based row of group names above them, or null
          title: Group Row
        header_row:
          description: 1-based row of the column names
          title: Header Row
          type: integer
      required:
        - header_row
        - group_row
      title: HeaderRows
      type: object
    FeedPeriod:
      properties:
        date_column:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A column dating each row's usage. Null: 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:
          enum:
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
            - sunday
          title: Week Start
          type: string
      required:
        - snapshot
        - date_column
        - week_start
      title: FeedPeriod
      type: object
    FeedSource:
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Email: the address to send files to'
          title: Address
        attachment_filter:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Email: a pattern that picks the file when an email carries several'
          title: Attachment Filter
        bucket:
          anyOf:
            - type: string
            - type: 'null'
          title: Bucket
        connection:
          anyOf:
            - type: string
            - type: 'null'
          description: 'S3: the AWS S3 connection, made in the app'
          title: Connection
        kind:
          description: How files reach the feed
          enum:
            - email
            - s3
            - sftp
          title: Kind
          type: string
        prefix:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
        subject_filter:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Email: only emails whose subject holds this'
          title: Subject Filter
      required:
        - kind
      title: FeedSource
      type: object
    ValidationRules:
      description: Validation rules for CSV processing.
      properties:
        allow_partial_success:
          default: true
          description: Allow some rows to fail while processing others
          title: Allow Partial Success
          type: boolean
        required_columns:
          description: List of required CSV columns
          items:
            type: string
          title: Required Columns
          type: array
        skip_on_error:
          default: false
          description: Skip processing if validation fails
          title: Skip On Error
          type: boolean
      title: ValidationRules
      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.