Query String Parameter
A query string parameter is a key-value pair appended to a Salesforce URL after the question mark character, used to pass data into a page when it loads.
Definition
A query string parameter is a key-value pair appended to a Salesforce URL after the question mark character, used to pass data into a page when it loads. The browser sends these values to the page so it can pre-fill fields, filter a report, set a return location, or otherwise shape what the user sees. A simple example looks like ?Name=Acme&Phone=5551234, where each parameter is separated by an ampersand.
In Salesforce you meet query string parameters in two common places. The first is record create pages, where an encoded defaultFieldValues string pre-populates fields on a new record. The second is HTML lead and case capture forms, where hidden inputs and URL values carry context such as the org Id, a return URL, and campaign tracking data from a marketing source into the new record.
Where query string parameters show up in Salesforce
The anatomy of a Salesforce URL parameter
Every query string parameter has the same simple shape. After the path, a question mark marks the start of the query string. Then each parameter is a name, an equals sign, and a value. Multiple parameters are joined with an ampersand. So /lightning/o/Account/new?defaultFieldValues=Name%3DAcme carries one parameter named defaultFieldValues whose value is an encoded field assignment. Values must be URL encoded, which matters more than beginners expect. Spaces become %20, and an equals sign inside a value becomes %3D. If you skip encoding, the browser can split your value at the wrong character and the page reads garbage. The report filter documentation makes this point directly: the filter value must be URI encoded, so characters like spaces have to be written in a form URLs understand. One more rule trips people up. Everything in a query string arrives as a string. A number like 35000 reaches the page as text, and the Boolean values true and false also arrive as strings. Whatever consumes the parameter has to parse it back into the type it actually needs before using it.
Pre-filling a new record with defaultFieldValues
The cleanest supported way to open a record create page with values already filled in is the defaultFieldValues parameter. You do not hand-build the string yourself. The lightning/pageReferenceUtils module gives you encodeDefaultFieldValues(), which turns a plain object of field names and values into the encoded form the URL expects. A matching decodeDefaultFieldValues() reverses it. You assign that encoded string to pageReference.state.defaultFieldValues on a standard__objectPage page reference, then pass the page reference to the navigation service. Salesforce documents the rest plainly: with standard actions, the default field values pass through the URL to the object as a string, and the redirect and replace is handled for you. The user lands on a new record form with the fields already populated. A few values cannot ride along this way. System-maintained fields such as Id or modification timestamps are silently ignored. Rich text fields are unsupported, date and time values must use ISO 8601 format, and passing recordTypeId through defaultFieldValues is not supported. Keep those limits in mind so you do not chase a value that will never stick.
Adding custom query parameters with PageReference.state
Sometimes you want to pass your own context, not field defaults. The state property on a PageReference is built for that. You add key-value pairs to state, and the navigation service turns them into query parameters so the page state can be bookmarked or shared. The values must all be strings, and the consuming code has to parse them into whatever shape it needs. Salesforce enforces a naming rule that surprises first-timers. Custom state properties must use a namespace prefix followed by two underscores. Use c__ for components that are not in a managed package, or your package namespace for ones that are. The PageReference object is also frozen, so you copy it with Object.assign({}, pageReference) before changing state, and you remove a property by setting it to undefined. There is a rendering catch worth knowing. In Lightning Experience and Experience Builder sites, a view does not rerender when only the query string changes. A component has to observe CurrentPageReference and compare the incoming state to react. Otherwise your parameter changes silently and nothing on screen updates.
Web-to-Lead and Web-to-Case form parameters
The other place query string parameters appear is in the HTML forms Salesforce generates for Web-to-Lead and Web-to-Case. These forms POST to a Salesforce endpoint, and they carry several control values. The org Id tells Salesforce which org receives the record. A return URL, named retURL, sends the visitor to a thank-you page after submission. A debug flag routes the submission to a debugging page so you can confirm the field mapping works. Marketers lean on these forms to keep attribution intact. You can add hidden inputs that carry UTM values, an internal source, or other context from the landing page into the new Lead or Case. If you include the Campaign field on the form, Salesforce inserts the new lead as a campaign member, which links the record straight to the campaign that drove it. Two cautions apply. Field names on these forms are the field Ids Salesforce generates, not the friendly labels, so copy them exactly from the generator. And only fields you place on the form are captured, so plan the hidden inputs before you publish.
Filtering reports and list views from a link
Query string parameters are not only for creating records. They also drive what a report shows. In Lightning Experience you can filter a report from its URL by appending filter value parameters. The first custom filter is fv0, the second is fv1, and so on. You start the query string with a question mark if the URL has none yet, or add an ampersand if it already carries parameters. A worked example helps. A link like /lightning/r/Report/<id>/view?queryScope=userFolders&fv0=New%20Business opens the report scoped to your folders and sets the first filter to New Business. The space is encoded as %20 because raw spaces break the URL. The limits are strict. Only the equals operator works, so you cannot express less than, starts with, or contains through the URL. Each filter takes a single value, you cannot add or delete filters this way, and the technique does not apply to historical tracking reports or to Salesforce Classic. Standard filters like the date range and scope are not numbered and cannot be set through these parameters. Inside those rules, a single shareable link can drop a colleague straight into a pre-filtered view.
Security and good habits with URL values
Query string parameters are convenient precisely because they are visible and shareable, and that is also their risk. Anything in the URL sits in browser history, in server logs, and in the address bar where anyone over your shoulder can read it. Salesforce states the point without hedging: even when using HTTPS, putting personal data in URL parameters is not safe. So treat the query string as public. Do not pass passwords, session tokens, full record bodies, or personal data you would not print on a postcard. Pass identifiers and small flags, then look up the sensitive detail server-side once the page loads. For lead and case forms, remember that a hidden input is hidden only in the rendered page, not in the submitted request, so never trust it as a security boundary. Two habits keep this tidy. Always URL encode values so special characters survive the trip. And write down the parameter patterns your org relies on, with the field names and expected values, so the next admin can read a link and understand it instead of reverse engineering it under pressure.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Query String Parameter.
Hands-on resources to go deeper on Query String Parameter.
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 a Query String Parameter?
Q2. What's a common use case?
Q3. Where is the parameter in the URL?
Discussion
Loading discussion…