Records

Records in Flatfile represent individual rows of data within your import workflows. They are instances of data that conform to the field definitions in your blueprints, containing the actual values that users import, validate, and transform.

​

What are Records?

A Record is a data instance that:

• Contains Data Values - Stores the actual imported data for each field
• Maintains State - Tracks validation status, errors, and processing history
• Supports Transformation - Allows data modification and enrichment

Records are the fundamental data units that flow through your import pipelines, from initial upload through final export.

​

Record Structure

​

Basic Record Anatomy

This is an example JSON response from the Flatfile API. For working with Records in your language, see our API Reference documentation

{
  "data": {
    "records": [
      {
        "id": "us_rc_YOUR_ID",
        "values": {
          "firstName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "John"
          },
          "lastName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "Smith"
          },
          "email": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "john.smith@example.com"
          }
        },
        "valid": true,
        "metadata": {},
        "config": {}
      }
    ],
    "success": true,
    "commitId": "us_vr_YOUR_ID",
    "counts": {
      "total": 1000,
      "valid": 1000,
      "error": 0
    },
    "versionId": "us_vr_YOUR_ID"
  }
}

​

Related Concepts

Records are central to the Flatfile data import process and interact with:

• Blueprints - Structure definitions that organize record fields
• Workbooks - Containers that hold record collections
• Fields - Blueprint definitions that records conform to
• Jobs - Background tasks that process records
• Actions - Workflows that operate on record data
• Listeners - Event handlers that respond to record changes

Records are the heart of your data import process, representing the actual information that flows through your Flatfile workflows from initial upload to final export.