Learn how DataRaptor Load uses Lookup Mapping to find an existing Salesforce record and link it to a new or updated record. See how an external ID or Salesforce record ID can connect a child to its parent without creating a duplicate—and why that distinction matters.

Multiple Choice

In a DataRaptor Load operation, which mapping type is used to link to an existing related record rather than creating a new one?

Lookup Mapping is the way to connect to an existing related record during a DataRaptor Load without creating a new one. It works by performing a lookup on the related object (often using an external ID or the related object’s Salesforce Id) to find the existing record, then it assigns that record’s Id to the lookup field on the child. This links the two records together while preserving the existing related record. For example, when loading a child record that needs to relate to an existing parent, you use a lookup mapping to locate the parent by its external key and set the child’s parent reference to that found Id. This is different from creating a new related record, which would happen if you used a mapping type designed to instantiate a new related record. Other options aren’t used for this purpose: a relationship query is for retrieving related data, and the other mapping concepts don’t specifically perform the lookup-and-link operation needed to reuse an existing related record.

When a Salesforce record needs to point to a related record that already exists, creating another copy is usually the last thing you want. A DataRaptor Load can connect the records instead. Its Lookup Mapping finds an existing record, retrieves its Salesforce ID, and places that ID in the appropriate relationship field on the record being loaded. The result is a link to the existing record—not a duplicate.

That distinction matters in OmniStudio. DataRaptors move data between JSON and Salesforce records, often as part of a larger flow that collects information, updates a customer record, or creates a related case or order. A small mapping choice can affect what gets created and how records connect. Understanding Lookup Mapping helps keep those relationships accurate and your Salesforce data tidy.

What Lookup Mapping does

A Salesforce relationship field stores a reference to another record. For example, a Contact might include an Account lookup field. That field doesn’t contain the Account’s name; it holds a reference to the Account record, represented by its Salesforce ID.

During a DataRaptor Load, Lookup Mapping tells the operation how to find the record that should fill that relationship field. It uses a value supplied in the incoming data—such as an external ID or a Salesforce ID—to search the related object. When it finds a match, the mapping assigns that record’s ID to the lookup field on the record being loaded.

Imagine loading a new Contact for a customer whose Account is already in Salesforce. The incoming data might include the Account’s external customer key. Lookup Mapping uses that key to locate the Account, then sets the Contact’s Account reference to the matching record. The Contact is new; the Account isn’t. That’s the key idea.

A quick example: connecting a Contact to an Account

Suppose an incoming JSON payload contains a customer’s details:


{

"firstName": "Maya",

"lastName": "Chen",

"accountKey": "CUST-4821"

}

The DataRaptor Load can use accountKey to search the Account object for a record with the matching external key. If it finds an Account, the operation uses that Account’s Salesforce ID to populate the Contact’s Account lookup field.

The flow is straightforward:

  1. Read the key from the incoming data.

  2. Search the related object for a record with that key.

  3. Retrieve the matching record’s Salesforce ID.

  4. Assign that ID to the relationship field on the record being loaded.

It’s a little like addressing a letter by a reliable account number instead of guessing from someone’s name. Names can change or repeat; a well-managed external key can be much more dependable. A Salesforce ID can also identify a specific record, though an external ID is often useful when data comes from another system.

Why not create the related record again?

Sometimes a DataRaptor Load needs to create several connected records at once. But when the parent record already exists, creating a new one can lead to duplicates. Two Accounts might represent the same customer, or a Contact might end up attached to a fresh Account that contains only part of the customer’s information.

Lookup Mapping helps avoid that situation. It lets the load operation reuse a record already in Salesforce and attach the new or updated record to it. That can support cleaner reporting, more reliable customer histories, and fewer confusing records for teams to sort through later.

There’s a practical side to this, too. Duplicate records can ripple into other systems and workflows. An automation might update one Account while a service team works from another. A report may count the same customer twice. The original issue can start with one missing relationship, but the effects rarely stay in one place.

Lookup Mapping versus related concepts

A related-object query and a lookup mapping may both involve relationships, but they serve different jobs. A query retrieves data. Lookup Mapping finds an existing record so a load can set a relationship to it.

That difference is easy to miss because both can involve searching across objects. A query might fetch an Account’s details for use in a response. Lookup Mapping, by contrast, is part of loading data: it helps assign the Account reference to a Contact, Case, or other record.

It also helps to separate linking from creating. If a load is meant to create a new related record, its configuration needs to describe that creation. If the goal is to reuse a related record, Lookup Mapping is the mechanism that finds it and links to it. The intended result should guide the setup: a new record, or a reference to an existing one.

The matching key matters

Lookup Mapping is only as reliable as the value it uses to find a match. If the incoming key is missing, formatted differently, or not unique, the lookup may fail or identify the wrong record. A value like “Northwind” could match more than one Account. A unique external ID is less ambiguous.

Before relying on a mapping, check that the source data and Salesforce field use the same format. Watch for leading zeros, extra spaces, differences in capitalization, and values that arrive as numbers in one system but text in another. These details sound small—because they are—but they can quietly break a match.

It’s also worth deciding what should happen when no record matches. The load may need to report an error, skip the relationship, or follow another defined path. That choice depends on the business process. For a required parent relationship, silently leaving the field blank could create records that look complete but aren’t connected properly.

Troubleshooting a lookup that doesn’t link

If a loaded record has a blank relationship field, start with the incoming value. Confirm that the expected key is present in the payload and reaches the mapping as intended. Then check the related Salesforce record: does it exist, and does its lookup field value match exactly?

Next, verify the object and field configuration. The lookup must search the intended related object and use the right field as its matching key. Also confirm that the DataRaptor has the access it needs to read the related record and update the target relationship field. A correct value can’t help if the load can’t see the record or write the reference.

If the wrong record gets linked, focus on uniqueness. A search key that returns multiple plausible matches is a data design problem as much as a mapping problem. A unique external ID gives the lookup a clear target. That makes the relationship easier to understand, maintain, and troubleshoot.

Good habits for dependable links

A few habits make Lookup Mapping easier to manage:

  • Use a stable, unique key when one is available.

  • Keep the source value and Salesforce field formats consistent.

  • Confirm that the related record exists before the load depends on it.

  • Define what should happen when a match is missing.

  • Test both a successful match and a missing or invalid key.

  • Check the resulting relationship in Salesforce, not just the load response.

These checks don’t need to become a big ceremony. They simply help catch the kinds of small mismatches that can be hard to spot after data has moved through several systems.

The takeaway

In a DataRaptor Load, Lookup Mapping connects a record to an existing related record. It searches using a value such as an external ID or Salesforce ID, retrieves the matching record’s ID, and writes that reference into the target record’s relationship field.

Use it when the parent or related record already exists and should be reused. Keep the matching key clear and unique, and decide how the load should behave when it can’t find a match. With those pieces in place, OmniStudio can load new or updated data while preserving the relationships that make Salesforce records useful.