With Formstack, you can replace your Salesforce web-to-lead, web-to-case, or web-to-anything forms with a Formstack form. This allows for more control over the form, prevents spam, and uses client-side validation. You can also use Formstack functionality such as Routing Logic, customized messages, multiple redirect URLs, and more.
The Salesforce - External Client App integration connects your form to Salesforce by signing in to Salesforce and approving access, rather than entering a username, password, and security token. Your Salesforce password is never shared with or stored by Formstack.
Although this article takes you through how to set up and add the Salesforce - External Client App integration to your Formstack form for the first time, we also offer a native Salesforce tool that allows you to build and customize a form inside your existing Salesforce ecosystem. If you'd like more information on this separate product, please reach out here to get in touch with our sales team or here if you'd like to see it in action.
Article Contents:
- What's different from the original Salesforce integration
- Add the Salesforce - External Client App integration
- Integration options
- Reconnect, re-authenticate, or disconnect
- Troubleshooting
Note: To use the Salesforce API, your Salesforce organization must use an edition that includes API access (for example Performance, Unlimited, Professional with API access, Developer, or Enterprise). The Salesforce user who approves the connection must have the API Enabled permission. It is recommended to connect using a dedicated integration user rather than a personal account, so the connection isn't affected if an individual leaves your organization.
What's different from the original Salesforce integration
| Original Salesforce integration | Salesforce - External Client App | |
| Sign-in | Salesforce username, password, and security token | "Connect with Salesforce" sign-in and approval |
| Security token | Required; must be refreshed when the password changes | Not used |
| Session renewal | Re-enter credentials if they change | Renewed automatically in the background |
| Salesforce sandbox | Separate login | Sandbox Mode toggle |
If your form already uses the original Salesforce integration, you can copy its object and field mappings into the new integration. See Import mappings from the original integration.
Add the Salesforce - External Client App integration
Step 1: Turn on the integration
- Open your form and go to the Settings tab.
- Choose Integrations in the left-hand panel.
- Use the search bar or select the CRM option, then locate Salesforce - External Client App and click Add.
Step 2: Connect to Salesforce
- Under Account Information, turn on Use Salesforce Sandbox only if you are connecting to a Salesforce sandbox org. Leave it off for production orgs.
- Install the Formstack Forms Salesforce Connector ECA for your Salesforce organization.
- Click Connect with Salesforce.
- You are taken to Salesforce. Log in (if prompted) and click Allow to approve Formstack's access.
- You are returned to the integration page in Formstack. Account Information now shows Connected to followed by your Salesforce identity.
Formstack requests permission to manage data through the Salesforce API and to stay connected after you sign out (so form submissions can be sent without you logged in).
Note: If you cancel on the Salesforce approval screen, nothing is connected and you'll see the message "Salesforce authorization was cancelled. The account was not connected." Click Connect with Salesforce to try again.
Step 3: Add objects
Once connected, the Object Mapping section appears.
- Click + Add Object.
- In Salesforce Object, search for and select the object you want to send data to (for example Lead, Contact, Case, or a custom object).
- If the object has more than one Record Type, choose one from Record Type. The fields shown are grouped to match the Salesforce page layout for that record type.
- Map your fields (see Step 4).
You can add multiple objects to a single integration, for example an Account and a Contact created together from one submission. Click Remove on an object to delete it.
If an existing legacy Salesforce integration exists on the page, you can also import mappings from that integration into the Salesforce - External Client App integration.
Step 4: Map fields
Each Salesforce field in the object's layout is listed with a mapping selector. Required Salesforce fields are marked with an asterisk (*). For each field, choose how its value is supplied:
| Type | What it does |
| Form Field | Sends the value from a field on your form. Pick the field from the dropdown. |
| Value | Sends fixed text. You can combine text with form data by clicking the Insert Fields buttons to add a field's value into the text. |
| Link | (Reference fields only.) Sets this field to the record created for another object in the same integration. For example, on a Contact, link Account ID to the Account you added above. Add the parent object first; Link only lists objects already on the integration. |
| Lookup | (Reference fields only.) Finds an existing Salesforce record and links to it. Choose the field to Match On in Salesforce, then the form field that supplies the value to search for. |
Only mapped fields are sent. Fields left unmapped or empty are skipped.
Step 5 (optional): Upsert
Some Salesforce fields can be used to update an existing record instead of always creating a new one. Fields that support this show a Use as upsert key checkbox.
A common upsert is the email address. If you map an Email field and check Use as upsert key, Formstack updates the Salesforce record with that email address if one exists, and creates a new record if none does. Without upsert, each submission creates a new record.
Another common use case is upserting a Contact from a Case. Add a Contact object and check Use as upsert key next to its Email field. On the Case object, set Contact ID to Link and select that Contact. Each submission creates a new Case, but a new Contact is only created if one with that email address doesn't already exist.
Note: Which fields can be upsert keys is determined by Salesforce. Formstack can't edit or force a field to be an upsert key.
Step 6: Save
Click Save Changes. The button is enabled once you've made a change and all required settings are valid.
Import mappings from the original integration
If your form already has the original Salesforce integration and you haven't added any objects to Salesforce - External Client App yet, an Import mappings from a legacy integration section appears after you connect.
- Click Import mappings.
- Review the imported objects and fields, and edit them as needed.
- Click Save Changes.
Importing copies your object and field mappings only. It does not change your existing connection. Objects that existed only in the original integration are recreated with a single section, so review any layout-specific settings after importing.
Integration options
These settings are found under Integration Options once you are connected.
| Option | What it does |
| Assignment Rule Header | Applies your Salesforce assignment rules to records created by the integration. |
| Auto-Response Emails | Allows Salesforce to send auto-response emails (for example for Leads or Cases). |
| Other Emails | Allows Salesforce to send other outbound emails triggered by the new record. |
| User Emails | Allows Salesforce to send emails to Salesforce users triggered by the new record. |
| User Timezone | Interprets date/time values using the connecting Salesforce user's timezone. |
| Ignore Error | Treats certain non-critical Salesforce errors as successes. |
| File Delivery | Choose how uploaded files are sent to Salesforce: Attachment (default) adds a classic Salesforce attachment on the record, or Salesforce Files stores the file in Salesforce Files so it appears in the record's Files related list. |
Sending file uploads
To send a File Upload or Signature field to Salesforce, map it on a file-capable object (for example Attachment, or ContentVersion with File Delivery set to Salesforce Files) and link it to the parent record. If a field accepts multiple files, all of them are sent.
Note: If any one uploaded file can't be retrieved or delivered, the integration reports a failure for that submission. Use Run Again (see Troubleshooting) after resolving the issue.
Error handling
- Allow Submission if Integration Fails: when checked, the respondent's submission still completes even if the Salesforce step fails.
- Integration Error Email Recipients: email addresses (comma separated) notified when the integration fails for a submission.
Run mode
Use the run mode options at the top of the integration page to choose when the integration runs for a submission.
Reconnect, re-authenticate, or disconnect
When connected, Account Information shows who you're connected as, with two options:
- Re-authenticate: sign in to Salesforce again, for example to switch to a different Salesforce user. Your mappings are kept.
- Disconnect: removes the Salesforce connection from this integration. Submissions will not be sent to Salesforce until you reconnect.
If Formstack loses access to Salesforce (for example the approval was revoked in Salesforce, or the Salesforce user was deactivated), the page shows: "Your Salesforce account has been disconnected. Please reconnect to continue using this integration." Click Reconnect with Salesforce and approve access again. Your mappings are kept.
Troubleshooting
Connecting fails
- "Salesforce authorization was cancelled. The account was not connected." You selected cancel (or Deny) on the Salesforce approval screen. Click Connect with Salesforce and choose Allow.
- "Salesforce authorization failed. Please try connecting again." Salesforce returned an error. Try again; if the problem continues, confirm the Sandbox toggle matches the org type you're signing into (production vs. sandbox), that your Salesforce user has the API Enabled permission, and that your Salesforce administrator allows the Formstack connected app.
- Wait a few minutes: Salesforce can take a few minutes to recognize a newly authorized app. If you're told access is blocked right after setup, wait and try again.
More than one matching record found
If more than one matching record is found for an upsert, the integration returns an error from Salesforce. Remove the duplicate record within Salesforce, then re-run the integration in Formstack.
Re-run a failed submission
If an integration fails upon submission, check your integration settings for errors in the connection or in the mapping of form fields. Then click any submission within your form's Submissions tab, expand Integration Status, and click Run Again. The integration will run and show a green Success or a red Failed message. If it failed, review your settings and try again.
If a submission fails because Salesforce is not connected, reconnect (see above), then Run Again.
Missing fields or objects
The integration shows the fields in the page layout assigned to the object (and record type) for the connecting Salesforce user's profile. If a field you need isn't listed, add it to that page layout in Salesforce, or connect as a user whose profile uses a layout that includes it. If an object doesn't appear in the search, confirm the connecting user has access to it.
Error messages
REQUEST_LIMIT_EXCEEDED: TotalRequests Limit exceeded. Salesforce limits the number of API calls in a 24-hour period. This error comes from Salesforce and indicates the limit has been reached. The exact limit depends on your Salesforce edition and licenses; contact Salesforce support for specifics.
Restricted picklist errors. These occur when a value that isn't defined in the Salesforce picklist is submitted.
- In Salesforce Setup, open the object and find the picklist field.
- Add the required value to the picklist, or turn off "Restrict this picklist to the values defined in the value set" if values outside the list should be allowed.
Field length errors (for example, "Job Address (City): data value too large"). The submitted data exceeds the field's maximum length in Salesforce.
- Use the error message to identify the field.
- Shorten the data being submitted, or increase the field length in Salesforce.
"The Salesforce integration is not connected. Please reconnect." The connection was removed or lost. Reconnect under Account Information, then re-run the submission.
For more error messages and suggested troubleshooting steps, see Salesforce - Commonly Returned Errors.