Flatfile subpackage_mapping API

openapi: 3.2.0
info:
  title: Reference subpackage_accounts Subpackage Mapping API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_mapping
paths:
  /mapping:
    post:
      operationId: create-mapping-program
      summary: Create a mapping between two schemas
      description: Creates a list of mapping rules based on two provided schemas
      tags:
      - subpackage_mapping
      parameters:
      - name: environmentId
        in: query
        description: The ID of the environment
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_ProgramResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_mapping_ProgramConfig'
    delete:
      operationId: delete-all-history-for-user
      summary: Delete all history for the authenticated user
      description: Deletes all history for the authenticated user
      tags:
      - subpackage_mapping
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                environmentId:
                  $ref: '#/components/schemas/type_commons_EnvironmentId'
    get:
      operationId: list-mapping-programs
      summary: List mapping programs
      description: List all mapping programs
      tags:
      - subpackage_mapping
      parameters:
      - name: pageSize
        in: query
        description: Number of programs to return in a page (default 10)
        required: false
        schema:
          type: integer
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of records to return
        required: false
        schema:
          type: integer
      - name: createdBy
        in: query
        description: Filter by creator
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_UserId'
      - name: createdAfter
        in: query
        description: Filter by creation time
        required: false
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: Filter by creation time
        required: false
        schema:
          type: string
          format: date-time
      - name: environmentId
        in: query
        description: The ID of the environment
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
      - name: jobId
        in: query
        description: A job ID to find mapping programs for
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - name: familyId
        in: query
        description: Filter by family
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_FamilyId'
      - name: namespace
        in: query
        description: Filter by namespace
        required: false
        schema:
          type: string
      - name: sourceKeys
        in: query
        description: Filter by source keys
        required: false
        schema:
          type: string
      - name: destinationKeys
        in: query
        description: Filter by destination keys
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_ProgramsResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
  /mapping/{programId}:
    get:
      operationId: get-mapping-program
      summary: Get a mapping program
      description: Get a mapping program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_ProgramResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
    patch:
      operationId: update-mapping-program
      summary: Update a mapping program
      description: Updates a mapping program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_ProgramResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_mapping_ProgramConfig'
    delete:
      operationId: delete-mapping-program
      summary: Delete a mapping program
      description: Deletes a mapping program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
  /mapping/{programId}/rules:
    post:
      operationId: create-rules
      summary: Add mapping rules to a program
      description: Add mapping rules to a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_MappingRulesResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_mapping_CreateMappingRulesRequest'
    delete:
      operationId: delete-multiple-rules
      summary: Delete multiple mapping rules
      description: Deletes multiple mapping rules from a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleIds:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_commons_MappingId'
                  description: Array of rule IDs to be deleted
              required:
              - ruleIds
    get:
      operationId: list-rules
      summary: List mapping rules
      description: List all mapping rules in a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_MappingRulesResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
    patch:
      operationId: update-rules
      summary: Update a list of mapping rules
      description: Updates a list of mapping rules in a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_MappingRulesResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_mapping_UpdateMappingRulesRequest'
  /mapping/{programId}/rules/{mappingId}:
    get:
      operationId: get-rule
      summary: Get a mapping rule
      description: Get a mapping rule from a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: mappingId
        in: path
        description: ID of mapping rule
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_MappingId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_MappingRuleResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
    patch:
      operationId: update-rule
      summary: Update a mapping rule
      description: Updates a mapping rule in a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: mappingId
        in: path
        description: ID of mapping rule
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_MappingId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_mapping_MappingRuleResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_mapping_MappingRuleConfig'
    delete:
      operationId: delete-rule
      summary: Delete a mapping rule
      description: Deletes a mapping rule from a program
      tags:
      - subpackage_mapping
      parameters:
      - name: programId
        in: path
        description: ID of the program
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_ProgramId'
      - name: mappingId
        in: path
        description: ID of mapping rule
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_MappingId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
components:
  schemas:
    type_property_FieldAppearance:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property_FieldSize'
      description: Control the appearance of this field when it's displayed in a table or input
      title: FieldAppearance
    type_property_StringConfigOptions:
      type: string
      enum:
      - tiny
      - normal
      - medium
      - long
      description: How much text should be storeable in this field
      title: StringConfigOptions
    type_mapping_ProgramResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_mapping_Program'
      required:
      - data
      title: ProgramResponse
    type_commons_MappingId:
      type: string
      description: Mapping Rule ID
      title: MappingId
    type_commons_Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    type_property_EnumPropertySortBy:
      type: string
      enum:
      - label
      - value
      - ordinal
      title: EnumPropertySortBy
    type_mapping_MappingRuleConfig:
      type: object
      properties:
        name:
          type: string
          description: Name of the mapping rule
        type:
          type: string
        config:
          description: Any type
        acceptedAt:
          type: string
          format: date-time
          description: Time the mapping rule was last updated
        acceptedBy:
          $ref: '#/components/schemas/type_commons_ActorId'
          description: User ID of the contributor of the mapping rule
        metadata:
          description: Metadata of the mapping rule
      required:
      - name
      - type
      title: MappingRuleConfig
    type_property_NumberConfig:
      type: object
      properties:
        decimalPlaces:
          type: integer
          description: Number of decimal places to round data to
      title: NumberConfig
    type_mapping_CreateMappingRulesRequest:
      type: array
      items:
        $ref: '#/components/schemas/type_mapping_MappingRuleConfig'
      title: CreateMappingRulesRequest
    type_commons_Action:
      type: object
      properties:
        slug:
          type: string
          description: '**This is deprecated. Use `operation` instead.**'
        operation:
          type: string
          description: This will become the job operation that is triggered
        mode:
          $ref: '#/components/schemas/type_commons_ActionMode'
          description: Foreground and toolbarBlocking action mode will prevent interacting with the resource until complete
        tooltip:
          type: string
          description: A tooltip that appears when hovering the action button
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ActionMessage'
        type:
          type: string
          description: '**This is deprecated.**'
        description:
          type: string
          description: The text that appears in the dialog after the action is clicked.
        schedule:
          $ref: '#/components/schemas/type_commons_ActionSchedule'
          description: Determines if the action should happen on a regular cadence.
        primary:
          type: boolean
          description: A primary action will be more visibly present, whether in Sheet or Workbook.
        confirm:
          type: boolean
          description: Whether to show a modal to confirm the action
        icon:
          type: string
          description: Icon will work on primary actions. It will only accept an already existing Flatfile design system icon.
        requireAllValid:
          type: boolean
          description: '**This is deprecated. Use `constraints` instead.**'
        requireSelection:
          type: boolean
          description: '**This is deprecated. Use `constraints` instead.**'
        inputForm:
          $ref: '#/components/schemas/type_commons_InputForm'
          description: Adds an input form for this action after it is clicked.
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ActionConstraint'
          description: A limitation or restriction on the action.
        mount:
          $ref: '#/components/schemas/type_commons_ActionMount'
        guide:
          $ref: '#/components/schemas/type_commons_Guide'
        guardrail:
          $ref: '#/components/schemas/type_commons_Guardrail'
        createdFrom:
          $ref: '#/components/schemas/type_commons_ActionId'
          description: The action that this action was cloned from
        lastPropagatedAt:
          type: string
          format: date-time
          description: The last time this action was propagated to a workbook
        deletedAt:
          type: string
          format: date-time
          description: The time this action was deleted
        invalidConditionalMessaging:
          type: boolean
          description: When enabled, shows dynamic confirmation messages based on record validation status instead of the static description
        validRecordsMessage:
          type: string
          description: Custom message to show when all records are valid (only used when invalidConditionalMessaging is true)
        invalidRecordsMessage:
          type: string
          description: Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true)
        label:
          type: string
          description: The text on the Button itself
      required:
      - label
      title: Action
    type_records_ValidationType:
      type: string
      enum:
      - error
      - warn
      - info
      title: ValidationType
    type_mapping_ProgramSummary:
      type: object
      properties:
        totalRuleCount:
          type: integer
          description: Total number of mapping rules
        addedRuleCount:
          type: integer
          description: Number of mapping rules added
        deletedRuleCount:
          type: integer
          description: Number of mapping rules deleted
      required:
      - totalRuleCount
      - addedRuleCount
      - deletedRuleCount
      title: ProgramSummary
    type_property_EnumPropertyConfig:
      type: object
      properties:
        allowCustom:
          type: boolean
          description: Permit the user to create new options for this specific field.
        options:
          type: array
          items:
            $ref: '#/components/schemas/type_property_EnumPropertyOption'
        sortBy:
          $ref: '#/components/schemas/type_property_EnumPropertySortBy'
          description: Sort the options by the value of this property. Defaults to `label`.
      required:
      - options
      title: EnumPropertyConfig
    type_property_RequiredConstraintConfig:
      type: object
      properties:
        message:
          type: string
          description: Custom validation message to display when the constraint fails
        level:
          $ref: '#/components/schemas/type_records_ValidationType'
          description: Validation level (error, warn, info). Defaults to error.
      title: RequiredConstraintConfig
    type_property_ReferenceListPropertyConfig:
      type: object
      properties:
        ref:
          type: string
          description: Full path reference to a sheet configuration. Must be in the same workbook.
        key:
          type: string
          description: Key of the property to use as the reference key. Defaults to `id`
        filter:
          $ref: '#/components/schemas/type_property_ReferenceFilter'
          description: Optional filter to narrow the set of records in the reference sheet used as valid values
      required:
      - ref
      - key
      title: ReferenceListPropertyConfig
    type_commons_ActorId:
      type: string
      description: Actor ID
      title: ActorId
    type_commons_InputConstraint:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons_InputConstraintType'
      required:
      - type
      title: InputConstraint
    type_sheets_CompositeUniqueConstraintConfig:
      type: object
      properties:
        message:
          type: string
          description: Custom validation message to display when the constraint fails
        level:
          $ref: '#/components/schemas/type_records_ValidationType'
          description: Validation level (error, warn, info). Defaults to error.
      title: CompositeUniqueConstraintConfig
    type_commons_ActionId:
      type: string
      description: Action ID
      title: ActionId
    type_mapping_ProgramConfig:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/type_sheets_SheetConfig'
          description: Source schema
        destination:
          $ref: '#/components/schemas/type_sheets_SheetConfig'
          description: Destination schema
        familyId:
          $ref: '#/components/schemas/type_commons_FamilyId'
          description: ID of the family to add the program to
        namespace:
          type: string
          description: Namespace of the program
        save:
          type: boolean
          description: Whether to save the program for editing later. Defaults to false. If true, the response will contain an ID and access token.
        rules:
          type: array
          items:
            $ref: '#/components/schemas/type_mapping_MappingRuleConfig'
          description: Mapping rules to use for the program. If present, the program will be created with these rules.
      required:
      - source
      - destination
      title: ProgramConfig
    type_mapping_MappingRule:
      type: object
      properties:
        name:
          type: string
          description: Name of the mapping rule
        type:
          type: string
        config:
          description: Any type
        acceptedAt:
          type: string
          format: date-time
          description: Time the mapping rule was last updated
        acceptedBy:
          $ref: '#/components/schemas/type_commons_ActorId'
          description: User ID of the contributor of the mapping rule
        metadata:
          description: Metadata of the mapping rule
        id:
          $ref: '#/components/schemas/type_commons_MappingId'
          description: ID of the mapping rule
        confidence:
          type: integer
          description: Confidence of the mapping rule
        createdBy:
          $ref: '#/components/schemas/type_commons_UserId'
          description: User ID of the user who suggested the mapping rule
        createdAt:
          type: string
          format: date-time
          description: Time the mapping rule was created
        updatedAt:
          type: string
          format: date-time
          description: Time the mapping rule was last updated
        deletedAt:
          type: string
          format: date-time
          description: Time the mapping rule was deleted
      required:
      - name
      - type
      - id
      - createdAt
      - updatedAt
      title: MappingRule
    type_commons_Guardrail:
      type: object
      properties:
        content:
          type: string
          description: Markdown guardrail for this action
      required:
      - content
      title: Guardrail
    type_mapping_MappingRuleResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_mapping_MappingRule'
      required:
      - data
      title: MappingRuleResponse
    type_mapping_MappingRulesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_mapping_MappingRule'
      required:
      - data
      title: MappingRulesResponse
    type_propert

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flatfile/refs/heads/main/openapi/flatfile-subpackage-mapping-api-openapi.yml