Custom form - Loops

Our form endpoint lets you add new contacts to your audience from an HTML form or using JavaScript.

Find the form endpoint

To submit data to Loops you will need to retrieve the form endpoint URL that’s linked to your Loops account.

Go to the Forms page in your Loops account.
Click on the Settings tab.
Copy the URL shown in the Form Endpoint field.

Form settings showing the Loops form endpoint URL

Create a form

In a form, add input elements for each of the contact properties you want to collect. The following contact properties can be added to a new contact via a Loops form endpoint:

Email email
First name firstName
Last name lastName
User group userGroup
Source source (default value is “Form” if omitted)
Notes notes
Mailing list subscriptions (read more)

The only contact property that can be updated on an existing contact via a form endpoint is userGroup.
Existing contacts can be added to new mailing lists via a form, but not unsubscribed.

You can also use any custom contact properties from your API settings page in your form.

Add contact properties

For each form field use the “API Name” value found from your API settings page as the name attribute.

Contact properties table with API field names

Here’s a simple example form that collects name, email address and assigns a custom user group:

<form
  method="post"
  action="https://app.loops.so/api/newsletter-form/<YOUR_FORM_ID>"
>
  <input type="text" name="firstName" required>
  <input type="email" name="email" required>
  <input type="hidden" name="userGroup" value="Website signups">
  <button type="submit">Sign up</button>
</form>

To add subscribers to mailing lists via a form endpoint, include a hidden field called mailingLists. You can use a single mailing list ID or to add subscribers to multiple lists, use a comma-separated list of mailing list IDs.

Make sure that any mailing list you add to a form is Public. You cannot subscribe contacts to private mailing lists from the form endpoint.

<form
  method="post"
  action="https://app.loops.so/api/newsletter-form/<YOUR_FORM_ID>"
>
  <input type="email" name="email" required>
  <input type="hidden" name="mailingLists" value="cly2xnjbn002z0mme68uog1wk, cly4xnjbn002x0mme28uog1wk">
  <button type="submit">Sign up</button>
</form>

If you need a hand integrating with your custom form, just contact support and we’ll help you integrate with your specific setup.

Submit with JavaScript

We recommend submitting forms using JavaScript because the endpoint responds with JSON. To do this, make a POST request to your form endpoint. Make sure to set the Content-Type header to application/x-www-form-urlencoded and to submit the form body with encoded values.

function handleSubmit() {
  const formBody = `firstName=${encodeURIComponent(firstName)}&email=${encodeURIComponent(email)}&mailingLists=${encodeURIComponent(mailingListIds)}`;

  // Change this URL to your own endpoint URL
  fetch("https://app.loops.so/api/newsletter-form/<YOUR_FORM_ID>", {
    method: "POST",
    body: formBody,
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
  });
}

function handleSubmit() {
  const formBody = `firstName=${encodeURIComponent(firstName)}&email=${encodeURIComponent(email)}&mailingLists=${encodeURIComponent(mailingListIds)}`;

  try {
    // Change this URL to your own endpoint URL
    const response = await fetch("https://app.loops.so/api/newsletter-form/<YOUR_FORM_ID>", {
      method: "POST",
      body: formBody,
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
    });

    if (response.status === 429) {
      // Handle rate limit error
      return {
        success: false,
        message: "Too many signups, please try again in a little while"
      };
    }

    // Returns `success=true` or `success=false`, plus an error message if false
    const data = await response.json();
    return data;

  } catch (error) {
    return {
      success: false,
      message: "An error occurred. Please try again."
    };
  }
}

Responses from this form endpoint will be one of the following:

HTTP 200

{
  success: true
}

HTTP 400 or 500

{
  success: false,
  message: "A descriptive error message."
}

Troubleshooting

Submissions to form endpoints are rate limited to a low number of requests per minute from each IP address. The endpoint will return a HTTP 429 response if requests exceed the rate limit. You should try to handle these responses gracefully in your form as shown in the example above.

​Find the form endpoint

​Create a form

​Add contact properties

​Subscribe to mailing lists

​Submit with JavaScript

​Troubleshooting

Find the form endpoint

Create a form

Add contact properties

Subscribe to mailing lists

Submit with JavaScript

Troubleshooting