Skip to main content

​
Overview

Typed CSV import lets you load per-contact data in bulk: one spreadsheet creates (or updates) your contacts and a typed custom variable record for each of them, linked and ready for calls to read. If you’re importing a call list where every row carries extra columns — a budget, a policy number, an appointment preference — this is how those columns become {{custom.<type identifier>.<field>}} values your scripts can speak. The import is driven by a custom variable type: you pick the type, map your CSV columns onto its fields, and every value is checked against the field’s data type before anything is written. If you haven’t built a type yet, start with Custom Variable Types & Schema Validation.

​
Where you can import

Typed CSV import appears in every place you upload contacts: Every entry point shares the same flow: choose or drop a .csv file (Excel files are not supported), review the parsed rows, optionally map custom variable columns, then import. The Contacts, Lists and Add Calls to Batch dialogs also have a Download CSV Template button with sample contact rows; the Batch Scheduler’s drag-and-drop area skips it, but its review step still offers the Typed template download once you choose a custom variable type. The Custom Variables page itself offers CSV download of the current table view, but no upload — typed records are imported through the contact flows above, or created individually with Add Custom Variable. The Contacts page CSV download round-trips with this import: alongside the contact columns, it writes one custom.<type identifier>.<field> column for every field of every custom variable type, filled from each contact’s linked records. You can export your contacts, edit the values in a spreadsheet, and re-import the same file — the headers map automatically.

​
Contact columns

The importer recognises these contact columns by header (alternate spellings such as first_name or phone also match): Rows that fail validation are listed in the review step with the reason and are excluded from the import. Rows repeating a phone number already seen in the file are skipped. In the Contacts importer, rows matching an existing contact’s phone number appear in a separate “Existing contacts to update” section — tick them to update those contacts instead of creating duplicates.

​
The custom.{type}.{field} header convention

Any column that isn’t a recognised contact column is treated as a candidate custom variable column. To have columns map themselves automatically, name them with the stable key convention:
The <type identifier> is the type’s internal identifier (e.g. property_listing), not its display name — see Custom Variable Types & Schema Validation for how that identifier is generated from the type’s display name. For example, for a Property Listing type:
Nested fields use their full dotted path, e.g. custom.property_listing.address.street. You don’t have to build the headers by hand. In the import dialog’s Per-contact custom variables panel, choose your type and select Typed template — it downloads a CSV with the core contact columns plus one correctly named column per field of the type, pre-filled with an example value matching each field’s data type. Auto-matching is forgiving: after stripping the custom. prefix, a header matches a field if it equals the field’s key, path or display label, ignoring case, spaces and punctuation. So Budget, budget and custom.property_listing.budget all map to the same field. Anything the importer can’t match you can map by hand.

​
Mapping columns to fields

In the review step, the Per-contact custom variables panel controls the typed import:
  1. Choose a type — pick a custom variable type from the dropdown, or leave it on Do not import custom variables to import contacts only.
  2. Map each column — every unrecognised CSV header appears with a dropdown of the type’s fields. Each option shows the field’s name and data type, and marks required fields; the batch import also shows the expected value format under each mapped column. Set any column you don’t want to Ignore column.
  3. Fix errors — every required field of the type must be mapped to a column, and every row must supply a value for it. Problems are listed per row, e.g. Row 2 (+61412345678): Budget: must be a number, and the import is blocked until they’re resolved: “Fix the custom variable errors before importing”. The row number counts the header as row 1 and follows the rows you’re importing — if earlier rows were dropped for failing contact validation or as duplicates, later row numbers no longer match their original line in the file.

​
Type conversion rules

Each mapped cell is converted according to the field’s data type. An empty cell leaves the field unset (unless the field is required, which is an error).

​
What happens when you import

For every selected contact, the import creates one typed record of its own and links it to that contact — contacts do not share a single record. The record is named after the contact (falling back to the phone number when no name is given). If a contact already has a linked record of the chosen type, that record is updated with the new values instead of a duplicate being created — so re-importing a refreshed spreadsheet is safe. Before writing, every record is validated against the type’s schema:
  • If the type’s validation mode is Strict, a record that fails validation stops the import with an error naming the contact and the problem.
  • Otherwise, mismatches are recorded as warnings and the data is saved anyway. See Custom Variable Types & Schema Validation for how the validation modes behave.
The batch flow confirms the result with a count of custom values created and updated. In the Contacts importer, if the contacts save but their typed values can’t be, you’ll see “Contacts imported, but their custom variables could not be saved.” — the contacts are kept, and you can re-run the import to attach the values. Once imported, the records appear on the Custom Variables page under their type’s tab, and each contact’s linked record feeds calls with that contact: your script reads {{custom.property_listing.budget}} (Number, e.g. 750000) or {{custom.property_listing.inspection_date}} (Text, e.g. 2026-07-21) from the record linked to whoever is on the call. How linked records are chosen at call time is covered on Linking Custom Variables to Contacts.

​
Next Steps