Flatfile subpackage_mapping API

openapi: 3.1.0
info:
  title: API 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_commons:ActorId:
      type: string
      description: Actor ID
      title: ActorId
    type_commons:Success:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_commons:SuccessData'
      description: Informs whether or not a request was successful
      title: Success
    type_mapping:ProgramResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_mapping:Program'
      required:
      - data
      title: ProgramResponse
    type_sheets:SheetConfig:
      type: object
      properties:
        name:
          type: string
          description: The name of your Sheet as it will appear to your end users.
        description:
          type: string
          description: A sentence or two describing the purpose of your Sheet.
        slug:
          type: string
          description: A unique identifier for your Sheet.
        readonly:
          type: boolean
          description: A boolean specifying whether or not this sheet is read only. Read only sheets are not editable by end users.
        allowAdditionalFields:
          type: boolean
          description: Allow end users to add fields during mapping.
        mappingConfidenceThreshold:
          type: number
          format: double
          description: The minimum confidence required to automatically map a field
        access:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets:SheetAccess'
          description: Control Sheet-level access for all users.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/type_property:Property'
          description: Where you define your Sheet's data schema.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons:Action'
          description: An array of actions that end users can perform on this Sheet.
        metadata:
          description: Useful for any contextual metadata regarding the schema. Store any valid json
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets:SheetConstraint'
          description: An array of constraints that end users can perform on this Sheet.
        treatments:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets:SheetTreatments'
          description: An array of treatments that define the behavior of the sheet.
        collection:
          type: string
          description: Collection in which to group the sheet
      required:
      - name
      - fields
      description: Describes shape of data as well as behavior
      title: SheetConfig
    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: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:EnumPropertyOption:
      type: object
      properties:
        label:
          type: string
          description: A visual label for this option
        description:
          type: string
          description: A short description for this option
        color:
          type: string
          description: An optional color to assign this option
        icon:
          type: string
          description: A reference pointer to a previously registered icon
        meta:
          type: object
          additionalProperties:
            description: Any type
          description: An arbitrary JSON object to be associated with this option and made available to hooks
        value:
          description: The value or ID of this option. This value will be sent in egress. The type is a string | integer | boolean.
        alternativeNames:
          type: array
          items:
            type: string
          description: Alternative names to match this enum option to
        ordinal:
          type: integer
          description: The order of this option in the list. SortBy must be set to `ordinal` to use this.
      required:
      - value
      title: EnumPropertyOption
    type_commons:Guide:
      type: object
      properties:
        content:
          type: string
          description: Markdown guidance for this action
      required:
      - content
      title: Guide
    type_property:FieldSize:
      type: string
      enum:
      - xs
      - s
      - m
      - l
      - xl
      description: The default visual sizing. This sizing may be overridden by a user
      title: FieldSize
    type_records:ValidationType:
      type: string
      enum:
      - error
      - warn
      - info
      title: ValidationType
    type_commons:InputConstraintType:
      type: string
      enum:
      - required
      title: InputConstraintType
    type_property:NumberConfig:
      type: object
      properties:
        decimalPlaces:
          type: integer
          description: Number of decimal places to round data to
      title: NumberConfig
    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_commons:ActionMode:
      type: string
      enum:
      - foreground
      - background
      - toolbarBlocking
      description: Foreground actions will prevent interacting with the resource until complete
      title: ActionMode
    type_sheets:SheetConstraint:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - unique
            description: 'Discriminator value: unique'
          name:
            type: string
            description: The name of the constraint
          fields:
            type: array
            items:
              type: string
            description: The fields that must be unique together
          requiredFields:
            type: array
            items:
              type: string
            description: Fields that, when empty, will cause this unique constraint to be ignored
          strategy:
            $ref: '#/components/schemas/type_sheets:CompositeUniqueConstraintStrategy'
          config:
            $ref: '#/components/schemas/type_sheets:CompositeUniqueConstraintConfig'
            description: Configuration options for the composite unique constraint
        required:
        - type
        - name
        - fields
        - strategy
      - type: object
        properties:
          type:
            type: string
            enum:
            - external
            description: 'Discriminator value: external'
          validator:
            type: string
          fields:
            type: array
            items:
              type: string
            description: The fields that must be unique together
          config:
            description: Any type
        required:
        - type
        - validator
      discriminator:
        propertyName: type
      title: SheetConstraint
    type_commons:ActionSchedule:
      type: string
      enum:
      - weekly
      - daily
      - hourly
      title: ActionSchedule
    type_mapping:ProgramsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_mapping:Program'
      required:
      - data
      title: ProgramsResponse
    type_commons:ActionMessageType:
      type: string
      enum:
      - error
      - info
      title: ActionMessageType
    type_property:ReferenceFilter:
      type: object
      properties:
        refField:
          type: string
          description: The field key of the reference sheet to filter with
        recordField:
          type: string
          description: The field key of the record used to filter the reference field
      required:
      - refField
      - recordField
      description: If provided, the reference filter will narrow the set of records in the reference sheet used as the set of valid values for the record. Only rows where the value in the reference sheet's refField matches the value in this record's recordField will be used.
      title: ReferenceFilter
    type_sheets:SheetAccess:
      type: string
      enum:
      - '*'
      - add
      - edit
      - delete
      - import
      title: SheetAccess
    type_commons:ActionId:
      type: string
      description: Action ID
      title: ActionId
    type_property:StringConfigOptions:
      type: string
      enum:
      - tiny
      - normal
      - medium
      - long
      description: How much text should be storeable in this field
      title: StringConfigOptions
    type_property:UniqueConstraintConfig:
      type: object
      properties:
        caseSensitive:
          type: boolean
          description: Ignore casing when determining uniqueness
        ignoreEmpty:
          type: boolean
          description: Do not flag empty values as duplicate
        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: UniqueConstraintConfig
    type_sheets:CompositeUniqueConstraintStrategy:
      type: string
      enum:
      - hash
      - concat
      title: CompositeUniqueConstraintStrategy
    type_commons:InputConstraint:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons:InputConstraintType'
      required:
      - type
      title: InputConstraint
    type_commons:ActionMessage:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons:ActionMessageType'
        content:
          type: string
      required:
      - type
      - content
      title: ActionMessage
    type_commons:EnvironmentId:
      type: string
      description: Environment ID
      title: EnvironmentId
    type_commons:InputForm:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons:InputFormType'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/type_commons:InputField'
      required:
      - type
      - fields
      title: InputForm
    type_commons:Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    type_property:StringConfig:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property:StringConfigOptions'
      required:
      - size
      title: StringConfig
    type_commons:InputField:
      type: object
      properties:
        key:
          type: string
          description: Unique key for a Field.
        label:
          type: string
          description: Visible name of a Field.
        description:
          type: string
          description: Brief description below the name of the Field.
     

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