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

# Setting Up CSV Integration

> Configure automated, email-based CSV data imports with the step-by-step wizard.

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.

<Tip>
  Looking for a one-time import instead? Use [Direct CSV Import](/data-import/direct_csv_import) to upload a file and import accounts or people immediately.
</Tip>

<Note>
  Setting up a CSV Integration requires Admin access.
</Note>

### 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

<Tip>
  Your sample file should have the same structure as files you'll import regularly.
</Tip>

***

### 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

<Tip>
  Custom account fields give you flexibility to match on any identifier unique to your business, such as an internal customer ID or billing code.
</Tip>

**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 Column  | Account 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.)

| Type                       | What to put in the CSV cell                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text, Long Text, Pick List | Any string. For Pick List, the value must match one of the field's defined options.                                                                            |
| Number, Float              | Numeric value                                                                                                                                                  |
| Percent                    | Number — with or without a trailing `%` (for example `42` or `42%`)                                                                                            |
| Currency                   | Number — symbols (`$`, `€`, `£`, `¥`) and thousands separators (`,`) are stripped automatically                                                                |
| Boolean                    | `true` / `false`, `1` / `0`, `yes` / `no`, or `on` / `off`                                                                                                     |
| Date                       | ISO date (`YYYY-MM-DD`) or a common date string                                                                                                                |
| Text List, Multi-Pick List | Use **semicolons** to separate multiple values (for example `High;Medium;Low`). For Multi-Pick List, each value must match one of the field's defined options. |
| URL                        | A URL string                                                                                                                                                   |
| Lookup (User, Owner)       | An email address that matches a user in your workspace                                                                                                         |

<Note>
  **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.
</Note>

***

### 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

   <Tip>
     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.
   </Tip>

4. **Add Metric Mappings**:
   * Select CSV column
   * Select or create a usage dimension
   * Choose data type (Numeric, Text, Boolean, Percent, Percent Ratio)

**Example:**

| CSV Column     | Dimension            | Type    |
| -------------- | -------------------- | ------- |
| "MAU"          | Monthly Active Users | Numeric |
| "API Calls"    | API Request Count    | Numeric |
| "Plan Type"    | Subscription Tier    | Text    |
| "Health Score" | Customer Health      | Percent |

<Note>
  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%`.
</Note>

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

<Warning>
  Testing does not save any data. It's a dry-run to validate your configuration.
</Warning>

***

### 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)

<Note>
  If you close the wizard with unsaved changes, a confirmation dialog will appear to prevent accidental data loss.
</Note>

**Deleting an Integration:**

1. Find your integration in the list
2. Click the delete icon
3. Confirm deletion

### Troubleshooting

<Accordion title="Accounts not matching">
  * Verify the identifier column contains valid data
  * Check that identifiers match exactly (case-sensitive for IDs)
  * Ensure accounts exist in Statisfy before importing
</Accordion>

<Accordion title="Fields not updating">
  * 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
</Accordion>

<Accordion title="Save rejected with 'unsupported field mappings'">
  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.
</Accordion>

<Accordion title="Email not processing">
  * Check the email address is exactly correct
  * Ensure the file attachment is under 50 MB
  * Verify the file is CSV or Excel format
</Accordion>