I am trying to import records to a custom multi-record set of fields. I read somewhere that it was a new feature for 4.5.8 but now for the life of me I cannot find where I read it - pretty sure it was the release notes, but may have got the version wrong.

Would appreciate a pointer in the right direction. (we are currently on 4.6.4)

Many thanks

  • Note this the import relates to multi-record sets attached to a contact record
    – Catherine
    Jul 15, 2015 at 16:37

4 Answers 4



  1. Contacts > Import Contacts
  2. Click the help ? at the end of: "The Import Wizard.... them here."
  3. Click the link on here at the end of: "If you need to import Multi-value Custom Data for contacts.... from here: /civicrm/import/custom?reset=1 .

You should see the multi-record field to import

  • 2
    May be helpful to include this link in your answer so people can get to it more easily ie /civicrm/import/custom?reset=1
    – petednz - fuzion
    Jul 16, 2015 at 0:23
  • 1
    Thanks so much Sanjay... I would never have found it! Agree with petednz - the link to multi record import needs to be much more obvious on Civi itself
    – Catherine
    Jul 21, 2015 at 10:13
  • can anybody in this thread help me with this question? civicrm.stackexchange.com/questions/19107/… Jun 21, 2017 at 4:01
  • I can't get this to work for dates :-( Dec 3, 2020 at 23:38

You can import multi-value custom fields through the API, including the API CSV Import GUI. You use the CustomValue API; you can also use the command-line CSV import tool or even drush.

Your contact ID field should be imported as entity_id. If the custom field ID is "4", then import to custom_4.

As an example - if your field set is called "schools attended", with custom fields "school" (custom field ID 7) and "degree" (custom field ID 8) for a contact with an ID of 123, your data may look like this:

entity_id | custom_7                 | custom_8
123       | University of Wisconsin  | BA
123       | Rutgers University       | MA
  • Trying this again and not possible via the API CSV Import GUI. The only select options I have are "Entity ID" and "- do not import -" -> I can't map any of my custom_ fields to any custom_ fields. This site is running ESR. I was looking for a UI option (so an admin could do it) but going command line now :-) Dec 3, 2020 at 22:34
  • Hmm - in API Explorer you can select "Other" instead of "Do Not Import". So much for my confidently incorrect answer :) Dec 4, 2020 at 18:10
  • I don’t get an Other option in API CSV import -> I ended up writing a little drush script - will post that here for completeness 🙂 Dec 4, 2020 at 19:40

If you have complicated import needs - for instance, you need to import multi-value custom fields as part of a larger import - you may want to consider the "Advanced Import-Form Processor" approach.

I really need to write docs up, but in general:

  • Install Form Processor.
  • Create a new form processor instance. Each "input" should correspond to a column in your source data.
  • When creating your actions, the "Update Individual" action won't import multi-value custom fields - but the "Contact: Update Custom Data" action will.
  • Test it out using the "Try Out" functionality to ensure it works as expected. Now the magic bit - how to use this as an import instead of for form submissions?
  • Install Advanced Import.
  • Install Advanced Import Form Processor.

Advanced Import gives you an import UI; Advanced Import Form Processor lets you use a Form Processor instance to process each line in your file. Advanced Import has some limitations (e.g. it doesn't handle large files well) and Form Processor is relatively slow - but you can create pretty much any import you need without coding by using these three extensions together. And it has an end-user focused UI. Much like Views or Webform, an admin can create something complex, but the end result is usable by end users.

Below is a screenshot of a Form Processor instance I created. I was given a list of students with their schools and related information. I was able to:

  • Create students if they didn't exist, or use existing contacts if they did (XCM integrates with Form Processor for very fine-grained duplicate matching).
  • Create the school if necessary.
  • Create a "Student/School" relationship that filled in relationship custom fields "Major" and "Degree". Note that you can import relationships with standard import, but can NOT import to relationship custom fields.
  • Imported alumni information, which is stored in a multi-record custom field group.

enter image description here


I ended up using a drush script to import data into custom multi record fields:

create file import-script.scr run it as: drush scr import-script.scr



$file = '/var/www/html/sites/default/scripts/civicrm_value_import.csv';

$fh = fopen($file, 'r');

while ($row = fgetcsv($fh)) {

  $contact_id = $row[8];
  if (empty($contact_id)) {

  // Build array for new data
  $import = [
    'entity_id' => $contact_id,
    'discharge_reason_329' => $row[14],
    'primary_presenting_problem_335' => $row[15],
    'principal_diagnosis_336' => $row[16],
    'diagnosis_2_337' => $row[17],
    'diagnosis_3_338' => $row[18],
    'opioid_dependency_339' => $row[19]
  if (!empty($row[11])) {
    $import += ['referral_date_331' => $row[11]];
  if (!empty($row[12])) {
    $import += ['enrolment_date_332' => $row[12]];
  if (!empty($row[13])) {
    $import += ['discharge_date_333' => $row[13]];
  if (!empty($row[21])) {
    $import += ['initiation_date_341' => $row[21]];
  //  print_r([$import]);

  // Insert

  // For testing one row
  // break;


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.