Calling the Account Engagement API from Salesforce
November 18, 2025
Ultimate Guide to Account Engagement External Actions
For years, Marketing Cloud Account Engagement (MCAE, formerly Pardot) users have relied on the Salesforce ↔ MCAE sync to drive their automations. Need to create a Task when someone fills out a form? Sync a hidden field. Want to update a Lead score or trigger a follow-up Flow? Add another mapped field.
It works… until it doesn’t.
The sync was designed to keep data aligned between systems, not to act as an automation engine. Every time you push or pull data through it, you’re adding complexity; two systems managing field values, validation rules that can break, and sync queues that take minutes to process. What should be a simple automation quickly turns into a maze of field mappings, validation errors, and unpredictable delays.
External Actions change that.
Instead of forcing information through the sync, External Actions let you send data directly from Account Engagement to Salesforce Flows, Apex code, or even other platforms. The result is faster, cleaner, and more reliable automation that runs when your marketing programs need it to… not five minutes later when the sync finally cycles through.
What External Actions Are (and Why They Matter)
External Actions are MCAE’s way of pushing data out of your marketing automation tool. They connect Engagement Studio programs, Completion Actions (Custom Redirects, Forms, Form Handlers) directly to Salesforce.
Think of them as a bridge: MCAE triggers an External Action, passes along key prospect data, and your Flow or Apex action takes it from there. No sync, no temporary fields, and no waiting.
To put it in context:
- External Activities bring data into MCAE (for example, logging webinar attendance).
- External Actions send data out of MCAE (for example, creating a Task or updating a Salesforce record).
The traditional MCAE Sync sits somewhere in the middle, trying to juggle both directions…but it was never built for event-based automation.
External Actions are available in Plus, Advanced, and Premium editions of Account Engagement. They can call Salesforce Flows or invoke Apex classes, which pretty much gives you the full power of the Salesforce Platform to do whatever you want.
When used well, they let marketers automate in near real-time, keep Salesforce clean, and eliminate the need for dozens of hidden fields that only exist to trigger syncs and potentially duplicate Flows (one on Lead, one on Contact).
How External Actions Work Behind the Scenes
The External Action has some configuration where it ties the Flow/Apex input variables to what MCAE might need to show in the User Interface. This configuration can be edited…but we’ll get to that later. Typically, you will either reference HML merge fields to pass data, or you might allow the Marketer to provide something hard-coded (such as a Campaign Id, or Form Name).
As for when Prospects do things, a new queue has been created in Salesforce, where these External Action requests build up. I’ve seen items in this queue take 10-60 seconds to process, though it will likely depend on how “fast” MCAE has been “feeling” lately.
When it's time for an External Action to “Act”, MCAE will prepare the request, apply any merge variables and then “fire” it off to Salesforce, as your Connector User. This means the Auto Launched Flow (or Apex) will be running as that Connector User, and anything you attempt to do will need to have the right permissions granted.
It’s important to note that the Prospect Data is merged at this later time, because if your Completion Action is on a Form, and the User quickly re-submits the form before the first Completion Action is processed (maybe making a new choice, or correcting a value), you will get a Completion Action for each submission, however the data might be the same (depending on timing).
Now, while you can have an External Action reference Apex directly, I’ve found it best to always use an Autolaunched Flow. This allows you to map & adjust incoming data a little better, as well as give you an easy spot to introduce debugging.
Use Cases: Where External Actions Shine
Here are some of the best ways to use them to clean up old sync-based workarounds and bring your automations closer to real time.
- Save Form Submission Details - store each submission as a record for analytics or compliance. For this to really work, you would want to make sure you don’t allow submissions in rapid succession. Keep the Form’s throttling setting on.
- Create Salesforce Tasks Dynamically - with complete control over owner, due date, etc.
- Do something with Agentforce - use a Prompt template and push the results back into MCAE
- Leverage Salesforce Data - use lookups or formulas to customize behavior based on CRM data. Great for performing field corrections such as state & country fixes (before syncing the Prospect record to Salesforce)
- Trigger 3rd-Party Integrations - send prospects into cadences, internal homegrown apps, or external apps (like Microsoft Teams, or your favorite Webinar platform).
Setting Up External Actions
Setting up External Actions might sound technical at first, but it’s surprisingly simple. After a quick one-time configuration, you’ll have a flexible framework ready for any automation you can imagine. For our example, we will demonstrate capturing a very simple form submission.
One Time Setup
This section you will only have to do once per org, unless you run into limits (there is a 10 Action limit per Extension) in which case you’ll have to create additional Marketing App Extensions. If you do plan to create a bunch, it might be worth looking into how you will organize them.
To get started, navigate to Salesforce Setup, then search for Marketing App Extensions. Create a new Extension.
- Extension Name: Provide your company’s name
- Extension API Name: Allow it to automatically populate
- Active in Automations: check the box (this allows it to be visible in MCAE)
- Description: (recommended) Enhancements built by our own company to improve automations in MCAE
Save the new record, then click on the Related tab.
Add a new Business Unit. When you click on the new button, a simple popup appears asking you to select the business unit.
You might have to begin typing the name and then search for it…it won’t appear nicely like most other lookup fields.
Save (and repeat for other business units if required).
Per Action Setup
This section you will perform for each action (up to a limit of 10).
Before doing these, you'll want to have your Autolaunched Flow ready to go. (We'll go through an example later)
- Create, test, and activate an Autolaunched Flow (we’ll go through an example soon)
- From the Related Tab of your Marketing App Extension, click the New button
- Action Name: A short descriptive label for the Action
- API Name: Allow it to automatically populate
- Description: Help your future self understand what this is and why it exists
- Invocable Action: Search for your Flow, select it
- Invocable Action Schema: Initially auto-populated, you can make adjustments to this (see below)
- Invocable Action Parameters: Initially auto-populated, safe to ignore and never change
- Active in Automations: check the box (this allows it to be visible in MCAE)
Pretty simple, right? Well, kind of. We will need to dig into creating the Autolaunched Flow, but before we do…there are a couple of gotchas we need to work through first.
Handling Data Types and JSON
When you’re building External Actions, one of the trickiest parts is handling data types correctly. Because the Marketing App Extension uses JSON behind the scenes, type mismatches can easily cause validation errors when your action runs. A little upfront planning in Flow goes a long way toward avoiding those headaches.
The Marketing App Extension only supports two data types: string and number. However, there’s a catch: merge fields (HML) can only be inserted into text inputs. MCAE will not let you merge a number field, as the merge syntax is text (you can’t even type it in).
To avoid data type issues entirely, the best practice is simple: use Text input variables only. Then, inside your Flow, create Formula resources that convert those Text values into the correct types when needed.
Here’s a quick reference for how to handle conversions safely in Flow:
- Numbers: VALUE( {!textInputVar} )
- Dates: DATEVALUE( {!textInputVar} )
- Booleans: {!textInputVar} = "true"
This approach ensures that your External Action always receives supported data types, while Flow handles any conversions you need internally.
Most data issues happen within Flow itself rather than MCAE. Be mindful of:
- Type mismatches: Using number or Boolean inputs instead of text (help yourself by planning your names and using descriptions).
- Null handling: Formula resources can fail if text inputs are blank—add default values or use BLANKVALUE() as needed.
- Unexpected formatting: Dates or numbers passed as text may need consistent formatting before conversion.
Keeping everything text-based at the entry point gives you complete control and ensures your External Actions run smoothly every time.
Building the Autolaunched Flow
Autolaunched Flows are quite powerful. They can be called from other Flows, Apex code, from other systems using the Salesforce API, and…well…now MCAE (with a little help from our External Action Schema instructions).
To get started, create a new Flow, then select the Autolaunched Flow. Next, create the Input Variables (Text) that you will need to accomplish your goal. While they will vary depending on your needs, here are the common ones you’ll probably want to include:
- firstName
- lastName
- salesforceId - the Lead/Contact Id for the Prospect if it has already been synced, which is not necessary for this to work
If you do include the salesforceId variable, you might want a couple of formula fields to turn it into lead / contact Id for use in your record creation elements.
- contactId (text): IF(BEGINS({!salesforceId}, '003'), {!salesforceId}, null)
- leadId (text): IF(BEGINS({!salesforceId}, '00Q'), {!salesforceId}, null)
You will also want to include formula fields for handling your Text -> Number/Boolean/Date field conversions.
Once all your variables are created, you can begin creating the “meat” of the Flow. In our example we are simply creating a new Form Submission record, but you can do whatever Salesforce allows in a Flow.
In our example, our Salesforce Custom Object for the submitted form entry has a Lookup to Lead and Contact, making these formula fields very handy. However to keep our data helpful and clean, we will need another Flow to populate the ContactId should the Lead be converted.
Flow's create record element, where we configure the field values to store the entire Form Submission details.
Build and test your flow, and when you think it is looking pretty solid you can save and activate it.
Adjusting the Invocable Action Schema
When initially creating the Action in the Marketing App Extension, the Action Schema JSON is automatically generated, and it assumes that the person in MCAE will have to provide each value when they use the Action.
Now, likely the fields you need in your Action will always be mapped to the same field. Luckily, we can adjust the Schema JSON so that the merge field is applied automatically and we can hide the field from the MCAE user interface.
First, let's break down the JSON into chunks.
Properties
This section lists each input variable that your Autolaunched Flow has. It has:
- The name of the input variable
- The type (should always be “string”)
- The title (which is set to the input variable name, but you can change it)
- The initial value, which you can provide your own value, including using HML variable merging
The first piece of the Invocable Action Schema, where we demonstrate each piece of each input variable.
View
This lists the input controls that are to be displayed inside MCAE.
You can edit this section to rearrange the order fields display, or you can remove them if you don’t want the Marketer to provide (or change your default) values as they use the External Action.
This is a great way to keep the inputs focused purely on what they need to provide or adjust.
The second piece of the Invocable Action Schema, where we demonstrate where the view inputs are organized.
Required
This section simply tells MCAE which fields in the External Action are required.
When working with an Autolaunched Flow, this section will be blank (as we don't have the ability to mark an Input Variable as required.
To add required fields, you will need to add comma-separated quote-enclosed input variable names.
The third piece of the Invocable Action Schema, where we demonstrate 2 fields having been marked as required for the External Action.
Our Example, modified
With our form submission example, a lot of our input variables can map directly to Prospect Fields, and it isn’t necessary to burden the Marketer to provide these details when the Action is used.
Here’s what our schema looked like when it was autogenerated (formatting adjusted to make it into a single screen)
Screenshot of entire External Action Schema, formatted for simplicity.
Next, we can provide the fields that we want to automatically map over. Yes, we could have mapped the favMascot too, but we wanted to leave it so that you can see the behavior. This is really handy for when you have a generic Action and want it to be reusable. You might want to capture something like a Salesforce Campaign Id which might differ every time it is used.
Next, we remove some of the inputs from the “components” block to simplify the UI in MCAE. We only want the "favMascot" to be provided when used.
And finally, here's how it will look when in use inside MCAE (both Form Completion Action and Engagement Studio Program Action)
Similar screenshot from above, modified for end-user simplicity.
Sending Data Back to Pardot (Advanced)
While it’s really cool that we can do all of these powerful things inside of Salesforce Flow, any changes to the data we make aren't really connected to MCAE at all. While it is possible to update the Lead/Contact record from Flow, this only works if our Prospects have been synced and we want to have these field values in Salesforce.
Ideally, what we would do instead is simply update the Prospect record directly. We would accomplish this by using the MCAE API.
To get this working, we will need a few things:
- An External Client Application (the new version of Connected App). Think of this as building the door and lock that allow other things to call the API.
- A Named Credential (along with External Credential). Think of this as minting the golden key that can unlock the door.
- Permission Set. Think of this as defining who is allowed to use the key.
- An action (HTTP Callout, or Apex) that performs the Update Prospect API method.
We broke out the first 3 steps into another post: Calling the Account Engagement API from Salesforce. It is quite involved, and if you want to skip the build, we’ve got a free AppExchange package that provides it all for you in a nicely wrapped box.
There is an out-of-the-box Flow Action called “Account Engagement: Upsert B2B Prospect”, however it only supports standard fields. Likely you will want the ability to update custom fields, in which case you’ll have to build something yourself.
Flow HTTP Callouts (which simply wrap External Services) is a mostly-declarative way to build something like this, however it is very rigid and generally not a good idea. You have to create unique “calls” for each combination of custom fields you want to update, providing JSON schema details and letting it generate Apex Defined Variables and making sure to populate everything so that values aren’t lost in MCAE. Apex is the best option for building a robust Action for passing information back to MCAE. You have control over which fields are sent, control over error handling and any additional value transformations necessary (which could reduce the need for Flow Formula variables). Our MCAE Toolbox has an Update Prospect action that makes this really easy to implement.
Best Practices & Common Pitfalls
By this point, you’ve probably realized that External Actions can be both incredibly powerful and a little touchy if not implemented with care. To keep your automations running smoothly, here are a few best practices…and a few “gotchas” you’ll want to avoid.
Best Practices
Always start with Autolaunched Flows first.
Even if your goal is to call Apex, start with a Flow. It’s faster to iterate, easier to debug, and gives you complete visibility into what data is coming in and what’s being sent back out.
Use HML merge fields for inputs wherever possible.
Rather than asking marketers to manually enter things like IDs or email addresses, rely on merge fields to populate those values automatically. This keeps actions reusable, reduces human error, and ensures that the right Prospect data is passed every time.
Keep data flows minimal.
External Actions don’t need to send entire records. Focus only on the fields your Flow or Apex logic actually needs. Passing unnecessary data makes maintenance harder and increases the chance of mapping or validation issues.
Stick to text input variables.
As covered earlier, while the App Extension only supports text and number types, only using text is the safest choice. Use Flow formulas to convert as needed (for example, VALUE() or DATEVALUE()), and you’ll avoid most JSON validation errors before they happen.
Document your schema changes.
If you edit the JSON schema for an External Action (for example, to auto-map merge fields or hide inputs), add a note in the record’s Description field explaining what was changed and why. Future you (or the next admin) will thank you later.
Keep your Connector User in mind.
All External Actions run as the Connector User, so that user’s permissions determine what your Flow or Apex can actually do. Make sure it has access to any custom objects, fields, or automation you’re referencing.
Common Pitfalls
Permissions and Connector User access.
This one causes the most trouble. Every External Action runs as your Connector User, which means the Flow or Apex it triggers can only access what that user can. Missing object or field permissions will cause silent failures or partial updates that are hard to spot. Always confirm that your Connector User has Create, Read, and Edit access for any records your Flow touches, and permission to run Flows in the first place.
Type mismatches and null values.
Most validation errors come from data types not matching what the External Action expects. Remember that JSON is strict: a blank value or unexpected format can break the request. Handle nulls and conversions inside your Flow before sending data anywhere.
Forgetting about timing.
External Actions don’t fire instantly. They typically process within 10-60 seconds depending on queue volume. If your automation depends on an immediate result, design with that delay in mind or trigger follow-up steps from Salesforce instead of MCAE.
Overcomplicating your setup.
It’s tempting to build dozens of specific Actions for different use cases. Resist that. Keep your setup simple and modular. One well-designed Flow can often serve multiple purposes by using input variables or conditional logic…just don’t build “one flow to rule them all”.
Wrapping Up
Even with the right setup and best practices, building and maintaining External Actions can take time. Between handling permissions, managing schema updates, and troubleshooting data mismatches, it’s easy to spend more time wiring things together than actually using them.
That’s exactly why we built the MCAE Toolbox, to take care of the hard parts for you.
