Print this page

Import related records using an External ID

Knowledge Article Number 000002783

Use an External ID in place of a related record's Salesforce ID to associate another object's record to another object's records in Salesforce upon Upsert via the Data Loader.

For example: If Object A and Object B are related to each other via a lookup relationship from Object B to Object A, you can import Object B records and relate them to Object A records via the lookup field using an External ID field on Object A.


Note: Always back up your data before performing any Data Loader operation by either Exporting Backup Data via the export service or by selecting to Export Data for the appropriate objects via the Data Loader. Run a test with one or a small subset of records to ensure the operation was successful by verifying the corresponding records in Salesforce are correct. Once you have confirmed the result is correct perform the appropriate Insert, Update, and/or Upsert operation for all records. 


Import related records using an External ID

An External ID field can be used to match or relate Object A records when importing Object B records without having Object A's Salesforce IDs. External IDs are commonly used to store unique record identifiers from external systems and allow for routinely loading data into Salesforce without having to prepare your file with existing or related Salesforce record IDs each time.

1. Identify an existing External ID field on Object A that you'd like to use for matching (or create an External ID via a new custom field with the Data Type "Text" on Object A) and select the External ID and Unique field attributes.

For more details, see these related help articlesCreate Custom FieldsCustom Field Attributes and What is an external ID?

2. Populate the new External ID field for Object A records in Salesforce (for use as the matching criteria when you import Object B records) by creating a .CSV file containing all Object A records by either Building a Report and Exporting a Report (If Object A records already exist in Salesforce) or by using the Data Loader to Export DataNote: Be sure to include the Salesforce IDs for Object A's records in your report or export file in order to perform an update to the record's new External ID field.

  • If importing new records, identify a column that contains data that would serve as a unique identifier for Object A records. Typically, this would be from a system outside of Salesforce and ideally these unique values for Object A records would already be contained in your Object B import file or commonly contained in files from an external system.

3. Perform an Insert for new records or perform an Update for existing records to Object A. Map required fields and the External ID column to the External ID field on Object A's records from step 1 (be sure to include and map Salesforce ID for an update or upsert operation) to populate a unique External ID value in Salesforce for all of Object A's records.

For more details, see this related help articleInsert, Update, or Delete Data Using Data Loader​

4. Prepare your Object B file with the related Object A record's corresponding External ID values you'd like to use for matching in order to populate the lookup field from Object B to Object A using the following method:

  • In the .CSV file for Object B, choose an existing column containing the unique data that matches the External ID values you set for Object A's records in steps 1-3 or create a new column named "External ID" and manually populate it (or use Excel's vlookup function) to bring over the External ID values set on Object A records.

5. In the Data Loader:

1. Click Upsert.
2. Select the appropriate object (Object B in our example).
3. Click Browse.
4. Select your import file for Object B.
5. Click Next.

6. In Step 2's "choose your related objects," select the External ID field for the Object A drop-down to use the External ID field for matching related Object A records upon importing Object B records.

7. In step 3's "mapping," drag and drop the Salesforce field with the name syntax [ObjectName]:[ExternalIDField__c] to map it to your Object B file's column containing the External ID values for Object A's records (in our example, the naming syntax [ObjectName] is "Object A" and [ExternalIDField__c] is the API name of object A's External Id field from step 1). 

  • By doing this you can easily relate Object B records to Object A records using the External ID that you created which eliminates the process of importing Object A records, Exporting the new IDs, matching them up in Excel and then importing the child records.

promote demote