Building a Named Query is a four-step process: design the query and parameters, register the Named Query in Setup, grant access to the right clients, and validate from a test client. The walkthrough below covers a typical partner-integration scenario where an external system needs to fetch Accounts by a custom external ID.
- Design the query and its parameters
Decide what data the integration needs, what filters it should pass at runtime, and what return shape makes sense. For an Account-by-external-ID lookup, the parameter is the external ID value, the query is SELECT Id, Name, Industry, BillingCity FROM Account WHERE External_Id__c = :param, and the return shape is the four selected fields. Confirm the parameter type (String, Id, Date, Decimal). Document the design before writing it into Setup so the integration owner can sign off on the contract before you ship anything.
- Register the Named Query in Setup
From Setup, navigate to Named Query API and click New. Provide a name (AccountByExternalId), a description, the SOQL string with bind variable placeholders, and the parameter definitions (name, type, required flag). Save. Salesforce validates the SOQL syntax and the parameter mappings, surfacing any errors. Iterate until the query saves without errors. The Setup page shows the Named Query with a unique API name that consumers will reference.
- Grant access to specific clients
On the Named Query's detail page, configure the access list. Add the specific Connected Apps, integration users, or client IDs that should be allowed to invoke this query. For each one, set whether they can invoke any version or only specific versions. Save the access control. Test the query from an unauthorized client to confirm it returns a 403 error, then test from an authorized client to confirm it returns the expected data.
- Document the API contract and validate from a test client
Document the Named Query's API contract: the endpoint URL, the parameter names and types, the return shape, and any rate or volume considerations. Share this with the integration owner so their developer can build against the contract. Run a sample request from Postman or another test client and confirm the response matches the documented contract. Promote the Named Query to production after sandbox testing, granting production access only to the production client IDs.
The unique identifier the client uses to invoke the query. Cannot contain spaces; must be globally unique within the org.
The query definition with named parameter placeholders. Must be syntactically valid SOQL at save time.
Each bind variable in the SOQL must be declared with a name, type, and required flag.
Required to create and edit Named Queries in Setup.
Without a configured access list, the Named Query cannot be invoked by anyone.
- SOQL injection is prevented by the bind-variable model, but the SOQL string itself must still be reviewed for performance and correctness. Bad SOQL is bad SOQL whether it is stored or constructed.
- Field-level security still applies. A Named Query that requests a field the integration user cannot read returns null for that field, which can confuse the consumer's logic.
- Versioning is per Named Query. Adding a field is a new version, not an in-place edit. Plan for consumer migration when you make changes.
- Result sets above 50,000 rows must use pagination cursors. Trying to return larger sets in a single call hits the standard SOQL row limit.
- Access control is at the Named Query level, not the parameter level. A client granted access to AccountByExternalId can pass any external ID value, not just the IDs that belong to their company.