Skip to main content
Follow this guide to set up a new CSV Integration. You’ll configure how your CSV data maps to Statisfy accounts and fields, and receive a dedicated email address for sending files automatically.
Looking for a one-time import instead? Use Direct CSV Import to upload a file and import accounts or people immediately.
Setting up a CSV Integration requires Admin access.

​
Start the Wizard

  1. Navigate to Integrations from the main menu
  2. Find CSV Import in the available integrations
  3. Click Add Integration to start the configuration wizard

​
Step 1: Basic Information

Enter a name for your integration:
  • Use a descriptive name like “Monthly Usage Report” or “Customer Data Sync”
  • Names can contain letters, numbers, and underscores
  • Spaces are automatically converted to underscores
Auto-Generated Email: Once you name your integration, a unique email address is generated:
Send CSV files to this email to trigger automatic imports.

​
Step 2: Upload Sample File

Upload a sample CSV or Excel file so the system can detect your columns:
  1. Drag and drop a file, or click to browse
  2. Supported formats: .csv, .xlsx, .xls (max 50 MB)
  3. The system will display:
    • Detected column headers
    • First 5 rows of sample data
Your sample file should have the same structure as files you’ll import regularly.

​
Header layout

If your files start with a title, a date, or notes before the column names, Statisfy detects it. Statisfy scans the top 20 rows of the sample file to find the column names row and an optional group names row above it. A Header layout line above the data preview summarizes the layout, for example column names in row 1 · no group row. When Statisfy detects that the column names aren’t in row 1, the Header layout card opens on its own and explains what it found. Otherwise, click Change to open it.
  1. Select the Column names row. Rows above it are ignored.
  2. Optionally, select a Group names row above it, or choose None.
  3. Check the Top of the file preview, which labels each row as ignored, groups, names, or data.
  4. Click Apply. Statisfy reads the sample file again with the new layout and refreshes the headers and preview.
With a group names row, Statisfy prefixes each column name with the group label above it, separated by /. For example, Logins under Module A becomes Module A / Logins. Statisfy saves the layout with the integration and uses it to read every file the integration receives, so keep the same layout in your recurring files. Example:
With Column names row set to Row 3 and Group names row set to Row 2, the columns are Account, Module A / Logins, Module A / Seats, and Module B / Logins. If the group name and the column name are the same, the column keeps its name.
Each file that the integration receives must have the same layout as your sample file. The integration reads the column names from the row that you saved. If a file has its column names in a different row, the run fails and lists the missing columns. To fix this, edit the integration and set the new layout.
Changing the layout or the file clears the previous test result, so run Step 6 again before you save.

​
Step 3: Account Identifier Mapping

Configure how CSV rows are matched to Statisfy accounts:
  1. CSV Column: Select which column contains the account identifier
  2. Match Field: Choose what to match against:
    • CRM Account ID - Best for Salesforce/HubSpot synced accounts
    • Domain - Company website domain
    • Account Name - Company name (less reliable)
    • Custom Account Field - Any custom field you’ve defined on accounts in the Object Manager
Custom account fields give you flexibility to match on any identifier unique to your business, such as an internal customer ID or billing code.
Preview: The wizard shows how your mapping will work with sample data.

​
Step 4: Account Fields (Optional)

Map CSV columns to update account custom fields:
  1. Click Add Mapping
  2. Select the CSV Column containing the data
  3. Select the Account Field to update — each option shows a type badge (for example Text, Number, Currency, Percent) so you can verify the CSV data is appropriate for the field
  4. Repeat for additional fields
Example Mappings: Skip this step if you only want to import product usage data.
Once you save the configuration, the fields you map become read-only in Statisfy. This applies to the account fields mapped here and to any custom object fields you map later in the wizard, on every record of that object. The CSV feed is now the source of their values, so change a value by correcting it in your file. To make a field editable again, remove its mapping from the configuration first, then turn Editable back on for that field in the Object Manager. Fields that also sync to your CRM are the exception and stay editable.

​
Supported custom field types

You won’t see account custom field types that can’t be populated from a CSV cell — the mapper hides them so you only pick from the types below. (Product usage metrics, configured in Step 5, follow slightly different rules — see that step’s notes.)
Not supported in CSV: Pill, Object, Lookup List, JSON, and Lookup fields that target an account or document. You won’t see these in the mapper, and the integration rejects them if you try to save a mapping that targets one.

​
Step 5: Product Usage Mapping

Map CSV columns to product usage dimensions. Each dimension belongs to a product, so choosing a dimension files the metric under that product. A single integration can feed as many products as your file covers — there is no product selection for the integration as a whole.
  1. Snapshot Period: Choose how often data is captured (Single, Daily, Weekly, Monthly, Quarterly, or Yearly). The snapshot period is set on the integration and applies to every product it feeds.
    Each product’s usage widget reads data at the product’s own configured period. If a mapped product expects a different period than the integration’s, the wizard shows an inline warning — usage written at the integration’s period will not appear on that product’s widget.
  2. Week Start Day (Weekly snapshot periods only): Choose which day your reporting week begins on. Defaults to Monday. See Product Usage Import for how this shapes the recorded date.
  3. Date Column (optional): Select a CSV column that contains the date for each row.
    • Auto-calculate (default) — dates are automatically calculated based on the snapshot period (e.g., first day of last month for Monthly)
    • Select a column — dates are read from the specified CSV column and snapped to the appropriate period boundary
    Use the date column option when backfilling historical product usage data. For example, if your CSV contains monthly usage for the past year, select the column that holds each row’s month/date.
  4. Add Metric Mappings: Click Add Metric, then for each row:
    • Select the CSV Column containing the data
    • Select the Usage Dimension. The picker lists every dimension in your workspace, each showing its product and key. Choosing a dimension settles both the product and the value type for that row — you don’t select them separately.
    Rows are grouped by product in collapsible sections; rows without a dimension yet appear under Unassigned. A dimension already used by another row is hidden from the picker, so each dimension can only be mapped once. To create a new dimension, first pick the product it belongs to in the Product for new dimension selector, then click New Dimension and enter its name and data type.
Example:
These rules apply to product usage metric mappings only — the account custom field rules in Step 4 are separate.Boolean values accept true / false, 1 / 0, yes / no, y / n, or on / off (case-insensitive).Numeric columns skip common missing-value markers (N/A, null, none, -, #N/A, #NA, nan, empty) instead of erroring on them. Percent and Percent Ratio columns must contain a plain number with no trailing % — for example 42, not 42%.
Skip this step if you only want to update account fields.

​
Step 6: Test Configuration

Validate your setup before going live:
  1. Upload a test CSV file (same format as your sample)
  2. Click Run Test
  3. The system processes the first 20 rows and shows:
    • Account Matches: Which accounts were found
    • Field Updates: Preview of data changes
    • Usage Records: Preview of metrics to record
    • Errors: Any rows that couldn’t be processed
  4. Review the results:
    • Green checkmarks indicate successful matches
    • Red warnings indicate issues to address
  5. Fix any issues and re-test if needed
If the column names are not in row 1, or the file has a group names row, the row numbers in the test errors are the row numbers in your file. Blank rows are counted.
Testing does not save any data. It’s a dry-run to validate your configuration.

​
Step 7: Review & Save

Review your complete configuration:
  • Integration name and email address
  • Account identifier mapping
  • Custom field mappings
  • Product usage mappings
  • Snapshot period settings
Options:
  • Activate Integration: Toggle on to enable automatic processing
  • Allow Multiple Rows Per Customer: Create new records instead of updating existing ones
Click Save to create the integration.
When you edit an integration and change its header layout, the column names can change and your saved mappings may no longer match. The wizard shows Run Test Configuration after a header layout change. and disables Save until a test in Step 6 passes.

​
How rows are processed

CSV Integration and Direct CSV Import follow the same rules when they write your data:
  • Account not found: a row whose account can’t be matched is skipped, not failed. The run lists it with its reason, for example Account not found for domain='nowhere.com'.
  • Repeated rows: rows for the same record are merged. For each field, the last non-empty value in the file wins.
  • Invalid cells: a cell that can’t be converted to its field type drops only that cell. Statisfy still writes the row’s other values and reports one error per bad cell, for example Failed to coerce field ....
  • Text cells: leading and trailing whitespace is trimmed before the value is written. A cell that is empty or contains only whitespace never overwrites an existing value.
  • Clear token: a feed clears a field from a cell only when its configuration sets a clear token. The token is off by default, so existing feeds do not change. When it is set, a cell that holds only the token (not case-sensitive) empties the field, and only when the field has a value now. The test results list these as clears. A date cell with -, N/A or NaT clears a date field with or without a token. The same fields as in Direct CSV Import are never cleared from a CSV.
  • AI-maintained fields: you can’t map a column to a field whose value is maintained by AI. Statisfy rejects the save with a 422 error and the reason field is maintained by AI. If a mapped field becomes AI-maintained later, each run skips it, counts the skipped writes, and still writes the other fields.
  • Non-editable fields: a write to a field that isn’t editable is skipped and counted in the run results. Fields this integration maps are read-only because the feed owns them, so they stay writable by the integration.

​
After Setup

Sending Data:
  1. Email CSV files to your integration email address
  2. Files are automatically processed when received
  3. Check the integrations dashboard for processing status
Updating Configuration:
  1. Find your integration in the list
  2. Click Edit to modify settings
  3. Your previously uploaded sample file is automatically loaded with the integration’s saved header layout, so all steps are immediately usable without re-uploading
  4. Save changes (integration name cannot be changed)
If you change the header layout, the column names can change. Check your mappings in Steps 3 to 5, then run Test Configuration again. The Update Configuration button stays disabled until the test passes.
If you close the wizard with unsaved changes, a confirmation dialog will appear to prevent accidental data loss.
Deleting an Integration:
  1. Find your integration in the list
  2. Click the delete icon
  3. Confirm deletion

​
Sending files larger than 20 MB

Email attachments are limited by the email provider, not by Statisfy. Keep attachments under 20 MB; anything above roughly 22 MB is rejected before Statisfy receives it. Because files are encoded for email transit and grow by about a third on the way, a 22 MB spreadsheet arrives as nearly 30 MB — the provider’s ceiling for the whole message, including the body and any other attachments.
An oversized attachment is rejected outright. The sending mailbox receives a bounce reading 550 Error reading data, max message size exceeded, and nothing appears in your job history because Statisfy never receives the message. If a recurring report stops arriving with no failed run to show for it, check the sending system’s delivery log for bounces.
You have three options, best first: 1. Send only the rows Statisfy can use. Rows whose account identifier is empty, or whose identifier doesn’t match an account in Statisfy, are discarded on arrival — they consume attachment size without producing data. Filtering them out at the source is usually the largest and simplest reduction. Your job history shows how many rows were skipped for each run, which tells you how much there is to gain. 2. Switch to Amazon S3. S3 delivery raises the ceiling to 200 MB per file and takes the email provider out of the path entirely. Statisfy checks the bucket every four hours rather than at the moment a file arrives, so allow for that when you schedule exports. This is the recommended option for files that keep growing. See S3 CSV Import. 3. Split the file across several emails. If the source system can’t filter or write to S3, export the data in parts and send each part to the same integration address as a separate email, each under 20 MB. When splitting, keep these rules in mind:
  • One file per email. Statisfy processes a single attachment per message, so two files on one email won’t both be imported — and their combined size would exceed the limit anyway.
  • Send all parts within the same period. With the default Auto-calculate date option (Step 5), the recorded date comes from when each email arrives, so every part must arrive inside the same snapshot period — the same reporting week for Weekly, starting on your configured Week Start Day, or the same month for Monthly. Parts that straddle a boundary are recorded as two separate periods instead of merging into one. If you’ve set a Date Column, the date comes from each row instead and arrival timing doesn’t matter.
  • Don’t split a single account across parts. Each part is processed independently, so keep all rows for a given account in the same file.
  • Check that every part arrived. Each email becomes its own run in your job history. If one part bounces or fails, the period is left partially populated, which looks like real data rather than an error — so confirm the expected number of runs after each cycle.
Splitting adds moving parts to every cycle and doesn’t stop a file from growing. Treat it as a bridge while you set up S3 or reduce what you send.

​
Troubleshooting

The wizard can find the wrong header layout in some files. The preview then shows wrong column names. Click Change in the Header layout card and set the rows yourself. These layouts often need a manual fix:
  • Group names above years. If the column names are years (for example 2024 and 2025), the wizard reads them as data and does not find the group row.
  • Merged cells in Excel files. The wizard cannot see where a merged cell ends. A column after the last group can show under that group. A column name that is merged down over 2 rows can show as a group name.
  • Files with only text. If a column name is blank and the data rows contain only text, the wizard can read the column names as group names.
The integration reads the column names from the header layout that you saved. If the file now has its column names in a different row, for example because a title row was added, the run fails and lists the missing columns. To fix this:
  1. Edit the integration.
  2. In Step 2, upload the new file and set the header layout.
  3. Check your mappings and run Test Configuration.
  4. Save the integration.
  • Verify the identifier column contains valid data
  • Check that identifiers match exactly (case-sensitive for IDs)
  • Ensure accounts exist in Statisfy before importing. Rows whose account isn’t found are skipped and listed with their reason in the run results
If the detected headers show a report title, a date, or blank names, the column names probably aren’t in row 1. Open the Header layout card in Step 2, select the correct Column names row, click Apply, and run Step 6 again. See Header layout.
  • Confirm the custom field exists on the Account entity
  • Check that the CSV column contains valid data for the field type (see the supported-types table in Step 4)
  • Verify field mapping is correct in configuration
  • If you mapped a Lookup-to-User or Lookup-to-Owner field, the CSV column must contain emails that match users in your workspace — rows with unresolved emails are reported as errors
The server returns 422 unsupported_field_mappings when a mapping targets a field type that Statisfy doesn’t read from CSV (Pill, Object, Lookup List, JSON, or a Lookup that targets an account or document), or when the target custom field key doesn’t exist in the Object Manager. Statisfy also rejects mappings to fields that are maintained by AI (field is maintained by AI) or aren’t editable (field is not editable), except fields this integration already maps. Remove those mappings or replace them with a supported field type, then save again.
  • Check the email address is exactly correct
  • Verify the file is CSV or Excel format
  • Check the attachment is under 20 MB. Larger files are rejected by the email provider before Statisfy receives them, so no run appears in your job history — instead the sending mailbox gets a bounce reading 550 Error reading data, max message size exceeded. See Sending files larger than 20 MB
  • If a recurring report stopped arriving and there’s no failed run to look at, check the sending system’s delivery log for bounces rather than the Statisfy job history