Skip to content



This hook allows an import row to be adjusted, after the user configuration has been interpreted into an apiv4-ready format. It is called twice. The first time the usage is validate and the second time the usage is import. In the validate usage you should avoid doing any db lookups or anything resource intensive. Validate mode is intended for a quick pass before presenting the preview screen. For the import usage you can do more intensive lookups and change the data if needed.


hook_civicrm_import_importAlterMappedRow(string $importType, string $context, array &$mappedRow, array $rowValues, int $userJobID)


  • @param string $importType This corresponds to the value in civicrm_user_job.job_type.
  • @param string $context import or validate. In validate context only 'cheap' lookups should be done (e.g. using cached information). Validate is intended to quickly process a whole file for errors. You should focus on setting or unsetting key values to or from 'invalid_import_value'.

During import mode heavier lookups can be done (e.g using custom logic to find the relevant contact) as this is then passed to the api functions. If a row is invalid during import mode you should throw an exception. - @param array $mappedRow (reference) The rows that have been mapped to an array of params. - @param array $rowValues The row from the data source (non-associative array) - @param int $userJobID id from civicrm_user_job


This hook was first available in CiviCRM 5.61 for contribution imports. Other imports will be added when the $mappedRow data is internally in APIv4 format (as we want the data to be stable when the hook is added).


This example shows replacing the contact Organization name with one determined from a custom function. (In this case the function is outside the example, but it looks in the legal name & nick name fields for for the name)

 * Implements hook_civicrm_importAlterMappedRow().
  function my_extension_civicrm_importAlterMappedRow(string $importType, string $context, array &$mappedRow, array $rowValues, int $userJobID) {
    if ($context === 'import' && $importType === 'contribution_import' && !empty($mappedRow['Contact']['organization_name'])) {
      $mappedRow['Contact']['organization_name'] = Contact::resolveOrganizationName($mappedRow['Contact']['organization_name']);