Forms for Email Signup

Setting up the form

Request a Form to be Created

Contact support to request that a form be created. This will be completed by our engineering team and the turn around time is about 1-2 business days or less.

When making a request, please specify the following:

Customer Lists – This is the lists you’d like to add your prospect to when they sign up. There must be at least one list.
On Success Redirect URL – Optional. Used for redirecting the customer to a branded success page on your website.
On Failure Redirect URL – Optional. Used for redirecting the customer to a branded failure page on your website.
- This will include a error query parameter to the URL

Important Notes

The error will be included as the error query parameter appended to this URL.
If an ID in this list is not found in the emailRecipientsListIds, it will silently ignore that insertion.
If the request supplies an array of acceptedListIds (i.e. IDs of the email recipient lists), it will add the user to only those list items in the list.
If none of the IDs in acceptedListIds are in the emailRecipientsListIds, the user is not added to any list.
If no list is provided, it will add the user to every list specified in emailRecipientListIds in the above section

Customer-facing form methods

There are multiple methods for the form to be published on a retailer’s website and used for capturing customer subscriptions:

Vanilla HTML form
Directly via Public Forms API, either through:
- Custom Javascript Frontend
- Custom Backend
Webhook by Third-Party Platform via Public Forms API
Hosted Form Page w/ Public Forms API (planned — not yet supported)
Javascript Library w/ Public Forms API (planned — not yet supported)

Vanilla HTML Form

Any basic html form will be able to submit to this form. Below is an example of a basic form that is enabled to submit to the above example:

<html>
	<body>
		<h1>Sign up</h1>
		<form action='https://api.bevsuite.com/forms/submit' method='POST'>
			<input type='hidden' name='formID' value='NyIPVmOL9c9eyHPpiyVZnOLGMxM1Ec51SY4jui3PbMsVAL'>
			<input type='text' name='email'>
			<input type='submit' value='Submit'>
		</form>
	</body>
</html>

Vanilla Form Parameters

Parameter	Type	Required	Description
formID	string	Yes	Public UUID hash value of the form, specific to the retailer. Supplied by BevSuite support.
email	string	Yes	E-mail address in proper https://datatracker.ietf.org/doc/html/rfc5322 format. The parameter name is case insensitive. The email value is case insensitive.
firstName	string	Optional	First name of the individual
lastName	string	Optional	Last name of the individual
acceptedListIds	array of numbers	Optional	Specifies the email list(s) to subscribe the individual to. If included, the list Ids are validated against the form configuration. If omitted, the individual will be assigned one or more default lists.

Please note:

Form Encoding – The example above assumes the default encoding of enctype="application/x-www-form-urlencoded". The form cannot be a enctype="multipart/form-data" form or other form encoding types
Action URL – The example above highlights that the action URL cannot have a trailing /
- Adding a trailing / will result in an error

Testing Vanilla HTML via Browser

A link to the above form can be found in each environment with the formID set to test:

https://api.bevsuite.com/forms/show

Testing Vanilla HTML via Curl

Invalid email:

curl -X POST 'https://api.bevsuite.com/forms/submit' \
	-H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'formID=test&email=bademailbevsuite.com'

Valid email:

curl -X POST 'https://api.bevsuite.com/forms/submit' \
	-H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'formID=test&email=goodemail@bevsuite.com'

Directly via Public Forms API

Overview

Form submissions can be provided to us directly via our Public Forms API. This gives you the flexibility of customizing it exactly how you want, without having to compromise on your customer experience.

This scenario is particularly useful in a couple scenarios, including:

Using javascript in your web site to send the request to us as a XHR request
Using a backend service to post the new submission
Using a third-party platform – see Webhook by Third-Party Platform

This section outlines the details around the API calls available to use for this purpose.

POST /forms/submit

Public Forms API Parameters

Error Responses

Status Code	Error	Description
400	Email is missing.	The email field is missing from the request
400	Email address is invalid.	The email doesn’t pass out validation and may not conform to RFC 5322
400	Invalid form type ‘’ for given formID.	This form type is not supported.
404	Form does not exist.	The formID provided does not exist. Please check the formID to ensure that it matches what was provided by BevSuite support.
500	Internal Server Error	Ensure you are using the correct formID provided by BevSuite support. If you experience this repeatedly, check our status page for any service outages or contact support for assistance.

Example Test Scenarios – JSON Encoding

Invalid email:

$ curl -i --location --request POST 'http://api.bevsuite.com/forms/submit' \
--header 'Content-Type: application/json' \
   -d '{ "formID": "test", "email": "bademailbevsuite.com" }' ;

Valid email:

$ curl -i --location --request POST 'http://api.bevsuite.com/forms/submit' \
--header 'Content-Type: application/json' \
   -d '{ "formID": "test", "email": "goodemail@bevsuite.com" }' ;

Example Test Scenarios – URL Encoding

Invalid email:

$ curl -X POST 'https://api.bevsuite.com/forms/submit' \
		-H 'Content-Type: application/x-www-form-urlencoded' -v \
		--data-urlencode "formID=test" \
		--data-urlencode "email=bademailbevsuite.com"

Valid email:

$ curl -X POST 'https://api.bevsuite.com/forms/submit' \
		-H 'Content-Type: application/x-www-form-urlencoded' -v \
		--data-urlencode "formID=test" \
		--data-urlencode "email=goodemail@bevsuite.com"

GET /forms/show

This returns a Vanilla HTML form that can be loaded in a browser for testing purposes. See the below example for the code that is produces.

Webhook by Third-Party Platform

In some cases, you may want to keep your existing third-party web platform (i.e. Wordpress, content management system, e-commerce platform, etc.) while integrating into our platform.

This can be accomplished by configuring your third-party platform to post the submissions to the POST /forms/submit endpoint as a webhook.

Set the webhook URL to https://api.bevsuite.com/form/submit
Set the Content-Type header to application/json
Add a formID field to the key provided by the Request a Form to be Created step
Specify at least the email field with the email address of your customer in the body of the message as a JSON object
1. firstName, lastName fields are optional.
2. acceptedListIds is also optional, but helpful if you want to give your customers control to specify the lists they want to be included on.
  1. The value must be an array of numeric list IDs unique to the retailer configuration, provided by BevSuite support.
  2. If this list is empty, it will subscribe the user to all lists configured for this form via the Request a Form to be Created step above.
3. Example Payload:
```
 {
 	"formID": "NyIPVmOL9c9eyHPpiyVZnOLGMxM1Ec51SY4jui3PbMsVAL", 
 	"email": "tom@bevsuite.com",
 	"firstName": "Tom",
 	"lastName": "M",
 	"acceptedListIds": [ 1, 2 ]
 }
```
Specify the HTTP Method as POST

Documentation