Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.statisfy.com/llms.txt

Use this file to discover all available pages before exploring further.

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: 
csv-{your-org-id}-{integration-name}@integrations.statisfy.com
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:
CSV ColumnAccount Field
”Industry”Industry (custom field)
“Employees”Employee Count
”Region”Sales Region
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.)
TypeWhat to put in the CSV cell
Text, Long TextAny string
Number, FloatNumeric value
PercentNumber — with or without a trailing % (for example 42 or 42%)
CurrencyNumber — symbols ($, €, £, ¥) and thousands separators (,) are stripped automatically
Booleantrue / false, 1 / 0, yes / no, or on / off
DateISO date (YYYY-MM-DD) or a common date string
Text ListUse semicolons to separate multiple values (for example alice;bob;carol)
URLA URL string
Lookup (User, Owner)An email address that matches a user in your workspace
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. 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:
    • Select CSV column
    • Select or create a usage dimension
    • Choose data type (Numeric, Text, Boolean, Percent, Percent Ratio)
Example:
CSV ColumnDimensionType
”MAU”Monthly Active UsersNumeric
”API Calls”API Request CountNumeric
”Plan Type”Subscription TierText
”Health Score”Customer HealthPercent
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

​
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
  • Ensure the file attachment is under 50 MB
  • Verify the file is CSV or Excel format