People & Directory

CSV Import & Export Guide

Kononia provides built-in tools for migrating large batches of contacts in and out of the People CRM using CSV files.

CSV Import & Export Guide

Kononia provides built-in tools for migrating large batches of contacts in and out of the People CRM using CSV files.

1. Import Specifications

To import contacts, navigate to the People directory and click Import CSV.

Required Columns

Your CSV file must include the following headers at a minimum:

  • first_name (required): First name of the contact.
  • last_name (required): Last name of the contact.

Supported Fields

The import parser checks headers by converting them to lowercase and replacing spaces with underscores (e.g., Birth Date becomes birth_date). The following headers are supported:

first_name, last_name, preferred_name, email, phone, mobile_phone, gender, date_of_birth, marital_status, membership_status, membership_date, campus, family_role, envelope_number, address_line1, address_line2, city, state, zip, country, email_opt_in, sms_opt_in, directory_visible

Parsing & Data Normalization Rules

  1. Boolean Conversion: For email_opt_in, sms_opt_in, and directory_visible, the system normalizes values of true, 1, or yes (case-insensitive) to true. All other values are converted to false.
  2. Quotes: Wrap fields containing commas or line breaks in double quotes (e.g., "123 Main St, Apt 4A"). Double quotes inside the values are escaped as double-double quotes ("").
  3. Organization Context: The importing utility automatically resolves the active user’s active organization_id and attaches it to every imported record.

Validation Preview

Once you select a CSV file, the utility parses the content locally and provides a dialog divided into two tabs:

  • Valid Tab: Lists all records that pass verification (i.e., contain both first_name and last_name). It displays preview columns like name, email, phone, and city.
  • Failed Tab: Identifies records missing required columns, showing the exact row number and validation error (e.g., Row 12: Missing first_name). Only valid records will be imported.

Batch Execution

Records are uploaded in sequential batches of 100 records to prevent network timeouts and stay within database limit constraints. Upon completion, the React Query cache is automatically invalidated for the query key ["people"].

2. Export Specifications

Clicking the Export CSV button in the directory triggers a complete download of the organization’s member roster.

  • Pagination Override: To bypass the standard Supabase response limit, the export utility queries records in sequential blocks of 1,000 records until all entries have been pulled.
  • Export Schema: The export includes all 23 supported columns listed above, sorted alphabetically by last_name.
  • Character Encoding: The generated file is packaged as a text/csv;charset=utf-8; Blob and downloaded through the browser using a timestamped filename (e.g., people-export-2026-06-05.csv).