Using Form Handler API in Marketing Cloud Next to Create Leads

Soumya Ranjan

4 min read

·

Sep 9, 2026

--

Listen

Share

Press enter or click to view image in full size

When we want to create a Lead from a website form, we can use a Form Handler in Marketing Cloud Next.

A Form Handler receives the form data and triggers a Salesforce Flow. The Flow can then perform actions such as:

• Create a new Lead
• Check whether the Lead or Contact already exists
• Capture email consent
• Update consent for an existing person

In my example, I created a simple Form Handler with the following fields:

• First name
• Last name
• Email
• Status
• Email Consent Capture

Do we need a new Form Handler for every form?

We can create one Form Handler for every new form. This is possible, but it may become difficult to manage when many forms are added over time.

For Lead forms that use the same fields and follow the same business process, we can use one common Form Handler and one reusable Flow.

This is where the solution design becomes important.

The Form Handler can receive the submitted data, and the Flow can decide what needs to happen next.

For example:

1. A person submits the website form.
2. The Form Handler receives the data.
3. The Flow checks whether a Lead or Contact already exists with the same email address.
4. If the person already exists, the Flow can update their consent.
5. If the person does not exist, the Flow can create a new Lead and capture their consent.

However, if a new form has very different fields or a different purpose, it may be better to create another Form Handler. The aim is not to force every form into one handler. The aim is to avoid building the same Lead and consent logic again and again.

Create the Form Handler

Go to:

Content > Content > Form Handlers

Press enter or click to view image in full size

Create a Form Handler and map these fields:

• First name
• Last name
• Email
• Status
• Email Consent Capture

Press enter or click to view image in full size

You can use the unique name to map e.g. ‘Last Name’ -> lastname. Eventually this map field is going to use as key in json payload.

After creating the Form Handler, create a Form-Triggered Flow and connect it to the Form Handler.

The Flow will receive the submitted values and perform the required actions.

Trigger the Form Handler through the API

After the Form Handler and Flow are ready, we can use the Form Handler API to submit data from an external website form.

The integration should call Salesforce from a server-side application. Do not expose the Salesforce client secret in website JavaScript.

First, generate an OAuth access token.

curl --request POST \
  --url 'https://YOUR_SUBDOMAIN.my.salesforce.com/services/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

Once the token is generated, use it to submit the form data.

curl --request POST \
  --url 'https://YOUR_SUBDOMAIN.my.salesforce.com/services/data/vXX.X/connect/form-handler/YOUR_FORM_HANDLER_CONTENT_KEY/submit' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Origin: https://www.yourwebsite.com' \
  --header 'Referer: https://www.yourwebsite.com/your-form-page' \
  --data '{
    "formData": {
      "firstname": "Test2",
      "lastname": "User2",
      "email": "test.user2@example.com",
      "leadstatus": "New",
      "email_consent": false
    },
    "uniqueId": "unique-submission-id"
  }'

Replace the following values:

• YOUR_SUBDOMAIN with your Salesforce My Domain subdomain
• vXX.X with the API version used by your org
• YOUR_FORM_HANDLER_CONTENT_KEY with the Content Key from the Form Handler
• YOUR_ACCESS_TOKEN with the OAuth token

The field names inside formData must match the external field names configured in the Form Handler.

Also, the website domain must be added to the Salesforce CORS allowlist. The Origin and Referer headers are required when calling the Form Handler submit endpoint.

Result

Once the API request is successful, the Form Handler triggers the Flow.

The Flow can then check whether the person already exists and either create a new Lead or update the existing person’s consent.

This gives us a reusable and controlled way to connect external website forms with Marketing Cloud Next and Salesforce.