Skip to main content

Import People (CSV): Contacts and Accounts

Updated

Purpose: This guide covers importing people: Accounts (companies and individuals), Contacts, and their account memberships and job roles.

Related: Importing data into Administrate | Choosing your import workflow

Order of operations

People data has a natural dependency order. Import in this sequence so each import's lookups can resolve:

  1. Accounts first (companies, and individual accounts if you use them).
  2. Contacts next, referencing their account.
  3. Memberships and Job Roles last, referencing both.

Importing Accounts

Choose the account record type. The main actions:

  • create for standard (company) accounts, and createIndividual for individual accounts. They are separate actions, so split your file if you are loading both kinds.
  • update and updateIndividual to change existing accounts by Administrate ID.
  • upsertByExternalId when a CRM owns the account list and you import from it repeatedly.

Importing Contacts

Choose the contact record type with create, update, or upsertByExternalId.

  • Identity on update: the contact identifier column accepts an Administrate contact ID or the contact's email address. An email must match exactly one contact or the row fails.
  • Emails and phone numbers are per-usage columns (for example separate landline, mobile, and fax number columns). On update, providing one usage updates that usage only; the others are retained.
  • Custom fields appear as their own template columns, one per field, labelled with your field names (for example "Contact - Custom Field - Contract Date"). They work on create, update, and upsert imports. Date custom fields take values in YYYY-MM-DD format. If a custom field column is missing from your file, you can add one yourself: head the column input/customFieldValues/<Field Name>, using the field's exact name (the match is case sensitive).
  • Custom System Fields do not appear on contact templates. These are the older, fixed built-in contact fields, renamed per instance and managed by Administrate; they do not appear in Control Panel → Custom Fields (see Custom Fields). Set them on the record or via the API. See Fields that do not appear on templates, which also covers fields whose template name differs from their screen label, such as Language appearing as Preferred Locale.

Memberships and Job Roles

A contact's job roles live on their account membership, imported with the membership record type:

  • add creates a membership with a job role.
  • addJobRole and updateJobRole manage job roles on an existing membership, including the role's Line Manager. See Line Managers and Supervisors for which manager field to use.

Watch out for

  • Synced accounts and contacts. If a CRM or HR system syncs people data into Administrate, that system probably owns it. See Importing when other systems are connected before importing.
  • Duplicates from create imports. Running a create against people who already exist makes lookalike duplicates. If existence is uncertain, check first or use upsert by external ID.
  • Ambiguous emails. If several contacts share an email address, rows identifying contacts by that email fail. Use Administrate IDs for those.
  • Blank cells never clear values and list fields replace in full on update. See Choosing your import workflow.
  • Pilot first, then verify: Verifying imported data.

Related articles