Integrate Form Submissions with the Connect API

Form handlers provide a method for using externally hosted forms to gather information and bring that information into Salesforce.

For security and scalability, we recommend that you use server-side processes to integrate form handlers directly with the API. In this type of integration, handling a form submission involves these steps:

  1. A user submits the form. The form payload includes a Marketing Cloud-generated form_id attribute as a hidden field or URL parameter.
  2. A server-side process receives the submission, processes it, and calls the Connect API. This process dynamically generates the correct endpoint URL using the form_id and constructs the request body based on the fields and values in the form.
  3. The Form Handler receives the API call and triggers a flow.

When a form submission triggers a flow, the flow can use the information in the form to send emails, update records, and perform other actions.

Before you configure your site to integrate with the Connect API, set up My Domain to create a subdomain that’s specific to your organization. When you use the API to handle form submissions, your API calls must use domains that use the format https://YOUR_SUBDOMAIN.my.salesforce.com.

Using other URLs results in a 403 Forbidden error. When you use a My Domain URL and a valid authentication method (usually an Authorization: Bearer header that includes an OAuth token) to make API calls, you’re granted full access to the Connect API.

  1. Create and publish a form handler and a corresponding flow. See Salesforce Help: Connect External Forms to Salesforce Objects by Using Form Handlers.
  2. Locate the Content Key for the form handler.

The Content Key is also referred to as the API Name. Find the Content Key on the details page for the form handler in Marketing Cloud Next or by using the Connect API to retrieve channel contents.

  1. Create a process hosted on your server that receives data from the form, processes it, and sends it to Salesforce via the Connect API.

    The implementation steps vary depending on your site’s technology stack, your organization’s code and security policies, and the structure and content of the information you capture in your forms.

    If your Form Handler requires reCAPTCHA, your server-side process can’t generate the validation token. Capture the token in the client browser during the initial form submission and pass it to your server-side process to include in the API payload.

    The process must send a POST request to your subdomain. The request endpoint includes the Content Key for the form handler, as shown in this example.

    The body of the POST request contains a formData object that includes the field names to update. The keys in the formData object must exactly match the external field names you configured in the Form Handler settings.