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.

​
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.

​
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 metrics:
  1. Select Product: Choose an existing product or create a new one
  2. Snapshot Period (read-only): The snapshot period is pulled from the product’s configuration in the Object Manager. If the product does not have a snapshot period configured, you’ll be prompted to set one in Admin > Settings > Object Manager > Products.
  3. 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.
  4. 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.
  5. Add Metric Mappings:
    • Select CSV column
    • Select or create a usage dimension
    • Choose data type (Numeric, Text, Boolean, Percent, Percent Ratio)
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, or short-hand t / f (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
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.

​
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, so all steps are immediately usable without re-uploading
  4. Save changes (integration name cannot be changed)
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

  • Verify the identifier column contains valid data
  • Check that identifiers match exactly (case-sensitive for IDs)
  • Ensure accounts exist in Statisfy before importing
  • 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. 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