External Lookup Relationship
An external lookup relationship is a Salesforce field that links a standard, custom, or external object record to a record held in an external system, with the join keyed on that external record's primary identifier.
Definition
An external lookup relationship is a Salesforce field that links a standard, custom, or external object record to a record held in an external system, with the join keyed on that external record's primary identifier. It is the Salesforce Connect mechanism that lets a Salesforce object point at a row sitting in SAP, an OData service, an Amazon Redshift cluster, or another Salesforce org without copying the data into the Salesforce database.
Unlike a regular lookup that points to a Salesforce record by Salesforce ID, an external lookup uses the external object's external ID field, which is the value the source system uses as its own unique key. The Salesforce record stores that key, and the platform resolves it on demand when a user opens the page or runs a report. This keeps a single source of truth in the external system while still letting users see, navigate, and report on the linked data inside Salesforce.
How external lookup relationships connect Salesforce to external systems
The Salesforce Connect dependency
External lookup only works on external objects exposed through Salesforce Connect. Those objects represent rows from an OData 2.0/4.0 service, a cross-org connector, or a custom adapter built with the Apex Connector Framework. Without an external data source registered in Setup, the external lookup field type does not appear as an option. Salesforce Connect is a paid add-on, licensed separately from base CRM, and the licensing math usually decides whether the project goes external-lookup or stays with traditional ETL.
Keyed on external ID, not Salesforce ID
An external lookup stores the external system's primary key, not a Salesforce ID. That key matches the external object's External ID standard field, which the platform marks as the unique identifier when the object is auto-generated from the data source schema. The relationship resolves at query time by passing the stored key back to the external service through the connector. If the external system rekeys its primary identifier, every external lookup pointing at the old key breaks silently.
Sharing and security inherit from Salesforce
The Salesforce record holding the external lookup follows normal Salesforce sharing, but the external object itself respects the named credential and the external user permissions configured for Salesforce Connect. A user with read access to the parent record may still be denied access to the external row if the connector credentials block them. Plan permission sets and named credentials together because the dual gate confuses users when they see a parent record but a blank external child.
Reporting and query limits
You can include external objects in reports through external lookup, but the report engine pushes the join down to the external system on every run. There is no caching of external rows in Salesforce unless you enable the Salesforce Connect cross-org option with an external object data cache. Each report run consumes API calls against the source system, and the external system has its own rate limits. Large dashboards built on external lookups can starve the external system of capacity during peak hours.
SOQL behavior through the relationship
Standard SOQL supports relationship queries through external lookups, but only one level deep in most cases and with restrictions on filter operators. Sub-query traversal in the SELECT clause goes through the connector and is subject to external-system pushdown rules. Joins on text comparisons work, but case sensitivity follows the external system's collation, not Salesforce defaults. Always test SOQL against the live external object before promising downstream consumers a clean reporting view.
External lookup versus indirect lookup
External lookup and indirect lookup look similar but solve opposite problems. External lookup goes from a Salesforce object to an external object record. Indirect lookup goes from an external object to a Salesforce record, keyed on a custom external ID on the Salesforce side. If you confuse the two during data modeling, the field type list silently shows you the wrong options and the relationship fails at runtime. Sketch the direction of the join before choosing the field type.
Operational behavior in production
When the external system is down or slow, external lookup fields render as blank or with a connector error inline on the page. Salesforce does not retry automatically and there is no Recycle Bin equivalent for external rows. If the external system deletes the source record, the Salesforce record still holds the stale key and the linked content disappears from the UI without warning. Build monitoring on connector health, and consider a fallback display value stored on the Salesforce side for critical fields.
How to create an External Lookup Relationship
An external lookup needs three pieces in place before the field type even appears: Salesforce Connect licensed, an external data source registered, and external objects generated from that source. Once the prerequisites exist, the field creation is straightforward, but the gotchas show up later in production when the external system blinks.
- Confirm Salesforce Connect is enabled and licensed
Check the Salesforce Connect add-on in Company Information. Without it, external data sources cannot be registered and the external lookup field type stays hidden. Talk to the account executive if it is missing, because Connect is licensed per external object and per user.
- Register the external data source
Setup, External Data Sources, New. Choose the connector type: OData 2.0, OData 4.0, Cross-Org, or a custom Apex adapter. Provide the endpoint URL, the named credential for authentication, and the certificate if mutual TLS is required. Validate the connection before saving.
- Sync the external object schema
From the external data source detail page, click Validate and Sync to pull the schema. Pick which tables to expose as external objects. The platform creates the external objects with __x suffix and a default external ID field. Review the field types it generated before continuing.
- Create the external lookup field on the parent object
Open the standard, custom, or external object that will hold the lookup. Fields and Relationships, New, External Lookup Relationship. Pick the target external object. The field stores the external system primary key as text, not as a Salesforce ID.
- Set field-level security and add to layouts
Configure FLS for the profiles that need to see the linked external data. Add the field to the page layout in the section that makes sense for the user journey. Verify the related list of external records appears where expected on the parent layout.
- Test sharing through the named credential
Log in as users with different profile and permission set combinations. Confirm they see the parent record and the linked external row resolves correctly. If the external row is blank, check whether the named credential restricts access on the external system side, not just the Salesforce side.
- Add monitoring for the external connection
Build a periodic health check that queries one external object record. Alert if response time exceeds the threshold the business can tolerate. Log connector errors centrally so support knows when blank external lookups are a connection issue rather than missing data.
The external object the lookup points at. Must be created from a Salesforce Connect external data source first.
The unique identifier from the source system. Auto-generated when the external object schema is synced.
Stores the endpoint URL and authentication for the external system. Without it, the relationship cannot resolve at runtime.
- Salesforce Connect is licensed separately from base CRM. The external lookup field type does not appear in Object Manager without the add-on, regardless of org edition.
- External lookups store the external system primary key, not a Salesforce ID. If the source system rekeys its identifier, every Salesforce record holding the old key breaks silently.
- Reports built on external lookups push the join to the source system on every run. Heavy dashboards can starve the external system of API capacity during business hours.
- There is no Recycle Bin for external rows. If the external system deletes a record, the Salesforce key remains but the data disappears with no audit trail on the Salesforce side.
- Sharing has two gates: Salesforce permissions on the parent, and the named credential plus external user permissions on the source. Users with read on the parent may still see blank external rows.
Trust & references
Cross-checked against the following references.
- Relationship Fields on External ObjectsSalesforce Help
- Salesforce Connect OverviewSalesforce Help
- Apex Connector FrameworkSalesforce Developer
Straight from the source - Salesforce's reference material on External Lookup Relationship.
- Relationship Fields on External ObjectsSalesforce Help
- External Data SourcesSalesforce Help
- Salesforce Connect ConsiderationsSalesforce Help
Hands-on resources to go deeper on External Lookup Relationship.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is an External Lookup Relationship?
Q2. Why does External Lookup use External ID instead of Salesforce ID?
Q3. What enables relational data models spanning Salesforce and external systems?
Discussion
Loading discussion…