Integrate Form Submissions with the Connect API

To use external forms to bring information into Salesforce, create a form handler.

For security and performance reasons, 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:

A user submits the form. The form payload includes a Marketing Cloud-generated form_id attribute as a hidden field or URL parameter.
A server-side process receives the submission, processes it, and calls the Connect API. This process dynamically generates the correct endpoint URL by using the form_id and constructs the request body based on the fields and values in the form.
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.

Prerequisites

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—such as an Authorization: Bearer header that includes an OAuth token—to make API calls, you get full access to the Connect API.

Form handler submission endpoints also enforce cross-origin resource sharing (CORS) validation. Add the domain of your server-side process to the CORS allowlist for your org. See Secure Your Salesforce Org: Configure Salesforce CORS Allowlist.

important: Include the Origin and Referer headers in every request to a Form Handler submit endpoint. Make sure that both values match an entry in your CORS allowlist. If a request doesn't include one of these headers, or if it uses an origin that isn't on the CORS allowlist, it fails with a 403 Forbidden or 404 Not Found error. This requirement applies to browser-based requests (which typically include these headers) and server-to-server requests (which include these headers only if you specify them).

Call the Connect API to Submit Form Data

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

tip: The Content Key is also called the API Name. Find the Content Key on the form handler details page in Marketing Cloud Next or by using the Connect API to retrieve channel contents.
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 technology stack, your security policies, and the type of information that you capture in your forms.

note: 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 sends a POST request to your subdomain. The request endpoint includes the Content Key for the form handler. Include the Origin and Referer headers in the request, and set both to a domain on your org's CORS allowlist.
```
curl -X POST "https://YOUR_SUBDOMAIN.my.salesforce.com/services/data/VERSION/connect/form-handler/YOUR_FORM_HANDLER_CONTENT_KEY/submit" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Origin: https://your-server.example.com" \
  -H "Referer: https://your-server.example.com" \
  -d @payload.json
```
The body of the POST request contains a formData object that includes the field names to update. Match the keys in the formData object to the external field names you configured in the Form Handler settings.
```
{
  "formData": {
    "firstName": "D'Angelo",
    "lastName": "Cunningham",
    "emailAddress": "dcunningham@example.com",
    "favoriteFruit": "Apples"
  },
  "uniqueId": "ce96199f-cd6e-431a-b4cf-20ccc9259999",
  "token": "03AFcWeA6nYqPzZcT1w9x8h4JkM2bXyFZr5u7C3A1BvLQmN0pEoR9s8DEXAMPLE"
}
```