openapi: 3.1.0
info:
  title: API Reference subpackage_accounts subpackage_records API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_records
paths:
  /sheets/{sheetId}/records:
    get:
      operationId: get
      summary: Get records
      description: Returns records from a sheet in a workbook
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: versionId
        in: query
        description: Deprecated, use `commitId` instead.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:VersionId'
      - name: commitId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sinceVersionId
        in: query
        description: Deprecated, use `sinceCommitId` instead.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:VersionId'
      - name: sinceCommitId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sortField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortField'
      - name: sortDirection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: filter
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: Name of field by which to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: ids
        in: query
        description: The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records. Maximum of 100 allowed.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - name: pageSize
        in: query
        description: Number of records to return in a page (default 10,000)
        required: false
        schema:
          type: integer
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of records to return (Note - numbers start at 1)
        required: false
        schema:
          type: integer
      - name: includeCounts
        in: query
        description: '**DEPRECATED** Use GET /sheets/:sheetId/counts'
        required: false
        schema:
          type: boolean
      - name: includeLength
        in: query
        description: The length of the record result set, returned as counts.total
        required: false
        schema:
          type: boolean
      - name: includeLinks
        in: query
        description: If true, linked records will be included in the results. Defaults to false.
        required: false
        schema:
          type: boolean
      - name: includeMessages
        in: query
        description: Include error messages, defaults to false.
        required: false
        schema:
          type: boolean
      - name: fields
        in: query
        description: A list of field keys to include in the response. If not provided, all fields will be included.
        required: false
        schema:
          type: string
      - name: for
        in: query
        description: if "for" is provided, the query parameters will be pulled from the event payload
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:EventId'
      - name: q
        in: query
        description: An FFQL query used to filter the result set
        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_records:GetRecordsResponse'
        '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'
    put:
      operationId: update
      summary: Update records
      description: Updates existing records in a workbook sheet
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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_versions:VersionResponse'
        '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_records:Records'
    post:
      operationId: insert
      summary: Insert records
      description: Adds records to a workbook sheet
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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_records:RecordsResponse'
        '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: array
              items:
                $ref: '#/components/schemas/type_records:RecordData'
    delete:
      operationId: delete
      summary: Delete records
      description: Deletes records from a workbook sheet
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: ids
        in: query
        description: A list of record IDs to delete. Maximum of 100 allowed.
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - 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'
  /sheets/{sheetId}/records/indices:
    get:
      operationId: indices
      summary: Get record Indices
      description: Returns indices of records from a sheet in a workbook
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: commitId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sinceCommitId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sortField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortField'
      - name: sortDirection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: filter
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: Name of field by which to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: ids
        in: query
        description: List of record IDs to include in the query. Limit 100.
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - name: q
        in: query
        description: An FFQL query used to filter the result set
        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_records:GetRecordIndicesResponse'
        '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'
  /sheets/{sheetId}/find-replace:
    put:
      operationId: find-and-replace
      summary: 'Finds and replaces field values matching search criteria

        '
      description: Searches for all values that match the 'find' value (globally or for a specific field via 'fieldKey') and replaces them with the 'replace' value. Wrap 'find' value in double quotes for exact match (""). Returns a commitId for the updated records
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: filter
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: Name of field by which to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: ids
        in: query
        description: The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - name: q
        in: query
        description: An FFQL query used to filter the result set
        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_versions:VersionResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                find:
                  $ref: '#/components/schemas/type_records:CellValueUnion'
                  description: A value to find for a given field in a sheet. For exact matches, wrap the value in double quotes ("Bob")
                replace:
                  $ref: '#/components/schemas/type_records:CellValueUnion'
                  description: The value to replace found values with
                fieldKey:
                  type: string
                  description: A unique key used to identify a field in a sheet
              required:
              - fieldKey
  /sheets/{sheetId}/records/bulk-update:
    patch:
      operationId: bulk-update
      summary: 'Bulk update records with field values

        '
      description: Updates multiple records at once with the same field values based on filter criteria. This is similar to a SQL UPDATE statement where you can update specific fields for all records matching certain conditions.
      tags:
      - subpackage_records
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: filter
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: Name of field by which to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: sortField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortField'
      - name: sortDirection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: ids
        in: query
        description: The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - name: q
        in: query
        description: An FFQL query used to filter the result set
        required: false
        schema:
          type: string
      - name: silent
        in: query
        description: Whether to suppress events for this bulk update
        required: false
        schema:
          type: boolean
      - 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_versions:VersionResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fieldUpdates:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/type_records:CellValue'
                  description: A map of field keys to cell values that will be applied to all matching records
              required:
              - fieldUpdates
components:
  schemas:
    type_commons:EventId:
      type: string
      description: Event ID
      title: EventId
    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_records:CellConfig:
      type: object
      properties:
        readonly:
          type: boolean
      description: CellConfig
      title: CellConfig
    type_commons:FilterField:
      type: string
      description: Use this to narrow the valid/error filter results to a specific field
      title: FilterField
    type_records:GetRecordsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_records:GetRecordsResponseData'
      required:
      - data
      title: GetRecordsResponse
    type_commons:CommitId:
      type: string
      description: Commit ID
      title: CommitId
    type_records:CellValueWithLinks:
      type: object
      properties:
        valid:
          type: boolean
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_records:ValidationMessage'
        metadata:
          type: object
          additionalProperties:
            description: Any type
          description: Deprecated, use record level metadata instead.
        value:
          $ref: '#/components/schemas/type_records:CellValueUnion'
        layer:
          type: string
        updatedAt:
          type: string
          format: date-time
        links:
          $ref: '#/components/schemas/type_records:Records'
      title: CellValueWithLinks
    type_records:RecordData:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_records:CellValue'
      description: A single row of data in a Sheet
      title: RecordData
    type_records:ValidationSource:
      type: string
      enum:
      - required-constraint
      - unique-constraint
      - custom-logic
      - unlinked
      - invalid-option
      - is-artifact
      title: ValidationSource
    type_records:ValidationType:
      type: string
      enum:
      - error
      - warn
      - info
      title: ValidationType
    type_commons:RecordId:
      type: string
      description: Record ID
      title: RecordId
    type_commons:SearchValue:
      type: string
      description: Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
      title: SearchValue
    type_commons:SheetId:
      type: string
      description: Sheet ID
      title: SheetId
    type_commons:Filter:
      type: string
      enum:
      - valid
      - error
      - all
      - none
      description: Options to filter records
      title: Filter
    type_commons:Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    type_records:RecordsWithLinks:
      type: array
      items:
        $ref: '#/components/schemas/type_records:RecordWithLinks'
      description: List of Record objects, including links to related rows
      title: RecordsWithLinks
    type_records:GetRecordsResponseData:
      type: object
      properties:
        success:
          type: boolean
        records:
          $ref: '#/components/schemas/type_records:RecordsWithLinks'
        counts:
          $ref: '#/components/schemas/type_records:RecordCounts'
        versionId:
          $ref: '#/components/schemas/type_commons:VersionId'
          description: Deprecated, use `commitId` instead.
        commitId:
          $ref: '#/components/schemas/type_commons:CommitId'
      required:
      - success
      - records
      description: A list of records with optional record counts
      title: GetRecordsResponseData
    type_commons:SuccessData:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      title: SuccessData
    type_records:RecordsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_records:RecordsResponseData'
      required:
      - data
      title: RecordsResponse
    type_records:RecordIndices:
      type: object
      properties:
        id:
          type: string
        index:
          type: integer
      required:
      - id
      - index
      description: A record index object
      title: RecordIndices
    type_versions:Version:
      type: object
      properties:
        versionId:
          $ref: '#/components/schemas/type_commons:VersionId'
      required:
      - versionId
      title: Version
    type_commons:SearchField:
      type: string
      description: Use this to narrow the searchValue results to a specific field
      title: SearchField
    type_records:RecordsResponseData:
      type: object
      properties:
        success:
          type: boolean
        records:
          $ref: '#/components/schemas/type_records:RecordsWithLinks'
        counts:
          $ref: '#/components/schemas/type_records:RecordCounts'
        versionId:
          $ref: '#/components/schemas/type_commons:VersionId'
          description: Deprecated, use `commitId` instead.
        commitId:
          $ref: '#/components/schemas/type_commons:CommitId'
      required:
      - success
      title: RecordsResponseData
    type_commons:Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type_commons:Error'
      required:
      - errors
      title: Errors
    type_records:RecordWithLinks:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_commons:RecordId'
        values:
          $ref: '#/components/schemas/type_records:RecordDataWithLinks'
        valid:
          type: boolean
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_records:ValidationMessage'
        metadata:
          type: object
          additionalProperties:
            description: Any type
        config:
          $ref: '#/components/schemas/type_records:RecordConfig'
      required:
      - id
      - values
      description: A single row of data in a Sheet, including links to related rows
      title: RecordWithLinks
    type_commons:SortDirection:
      type: string
      enum:
      - asc
      - desc
      description: Sort direction - asc (ascending) or desc (descending)
      title: SortDirection
    type_records:Record:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_commons:RecordId'
        versionId:
          $ref: '#/components/schemas/type_commons:VersionId'
          description: Deprecated, use `commitId` instead.
        commitId:
          $ref: '#/components/schemas/type_commons:CommitId'
        valid:
          type: boolean
          description: Auto-generated value based on whether the record contains a field with an error message. Cannot be set via the API.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_records:ValidationMessage'
          description: This record level `messages` property is deprecated and no longer stored or used. Use the `messages` property on the individual cell values instead. This property will be removed in a future release.
        metadata:
          type: object
          additionalProperties:
            description: Any type
        config:
          $ref: '#/components/schemas/type_records:RecordConfig'
        values:
          $ref: '#/components/schemas/type_records:RecordData'
      required:
      - id
      - values
      description: A single row of data in a Sheet
      title: Record
    type_commons:SortField:
      type: string
      description: Name of field by which to sort records
      title: SortField
    type_records:RecordDataWithLinks:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_records:CellValueWithLinks'
      description: A single row of data in a Sheet, including links to related rows
      title: RecordDataWithLinks
    type_versions:VersionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_versions:Version'
      required:
      - data
      title: VersionResponse
    type_records:FieldRecordCounts:
      type: object
      properties:
        total:
          type: integer
        valid:
          type: integer
        error:
          type: integer
        empty:
          type: integer
      required:
      - total
      - valid
      - error
      - empty
      title: FieldRecordCounts
    type_records:ValidationMessage:
      type: object
      properties:
        field:
          type: string
        type:
          $ref: '#/components/schemas/type_records:ValidationType'
        source:
          $ref: '#/components/schemas/type_records:ValidationSource'
        message:
          type: string
        path:
          $ref: '#/components/schemas/type_commons:JSONPathString'
          description: This JSONPath is based on the root of mapped cell object.
      description: Record data validation messages
      title: ValidationMessage
    type_records:RecordConfig:
      type: object
      properties:
        readonly:
          type: boolean
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_records:CellConfig'
        markedForDeletion:
          type: boolean
      description: Configuration of a record or specific fields in the record
      title: RecordConfig
    type_commons:JSONPathString:
      type: string
      description: A JSONPath string - https://www.rfc-editor.org/rfc/rfc9535
      title: JSONPathString
    type_records:GetRecordIndicesResponse:
      type: array
      items:
        $ref: '#/components/schemas/type_records:RecordIndices'
      title: GetRecordIndicesResponse
    type_records:CellValueUnion:
      oneOf:
      - type: string
      - type: integer
      - type: integer
        format: int64
      - type: number
        format: double
      - type: boolean
      - type: string
        format: date
      - type: string
        format: date-time
      - type: array
        items:
          type: string
      title: CellValueUnion
    type_records:RecordCounts:
      type: object
      properties:
        total:
          type: integer
        valid:
          type: integer
        error:
          type: integer
        errorsByField:
          type: object
          additionalProperties:
            type: integer
        byField:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_records:FieldRecordCounts'
          description: Counts for valid, error, and total records grouped by field key
      required:
      - total
      - valid
      - error
      title: RecordCounts
    type_records:CellValue:
      type: object
      properties:
        valid:
          type: boolean
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_records:ValidationMessage'
        metadata:
          type: object
          additionalProperties:
            description: Any type
          description: Deprecated, use record level metadata instead.
        value:
          $ref: '#/components/schemas/type_records:CellValueUnion'
        layer:
          type: string
        updatedAt:
          type: string
          format: date-time
      title: CellValue
    type_records:Records:
      type: array
      items:
        $ref: '#/components/schemas/type_records:Record'
      description: List of Record objects
      title: Records
    type_commons:VersionId:
      type: string
      description: Version ID
      title: VersionId
  securitySchemes:
    default:
      type: http
      scheme: bearer