Formstack Integration Overview

  • Updated

The Formstack integration adds people to your Community automatically when they submit one of your Formstack forms. Formstack sends each submission to Community through a webhook, and Community sends a welcome message by SMS to the phone number on the form.

Who this applies to: Leaders on select usage-based plans. Your account needs the API Tokens permission, which your Account Manager enables, plus a valid API token and a Formstack account. If you're not sure whether your plan includes it, contact your Account Manager or yourfriends@community.com.

 

What is the Formstack integration

The Formstack integration connects a Formstack form to your Community account. When someone submits the form, Formstack posts the submission to a Community webhook URL. Community reads the fields it recognizes and sends a welcome message by SMS from your Community number.

Community only recognizes fields that use specific internal labels. Phone number is the only required field. Name, email, location, date of birth and gender identity are optional and come through when you include them with the right labels. 

 

Why should I use the Formstack integration?

If you already collect phone numbers with Formstack, the integration turns those submissions into Community signups without a manual export and import. The welcome message goes out as soon as the form is submitted, while the person still has your brand in mind, rather than whenever a list is next uploaded.

Because the form fields map to Community, details people give you on the form, like their name and location, can arrive with their phone number instead of being collected again later.

 

How do I use it?

Setup happens mostly in Formstack. You'll create an API token in Community, set up your form fields with the right internal labels, then add a webhook that points at your Community account.

Creating an API token

  1. In Community, go to Settings > API Tokens.
  2. Create a new API Token. 

Keep the token private. It gives API access to your Community account.

 

Setting up your form fields

Give each field you want Community to read the internal label in the table below. The label has to match exactly. A field with a different label is not recognized, and its data does not reach Community.

For a working reference, see Community's example Formstack form.

Field Internal label
Phone number (Required) phone_number
Name name using the sub-fields first and last
Email email
Address Use the sub-fields city, state and zip
Date of birth date_of_birth
Gender identity male, female, non-binary or no-answer
Country country

Here is a sample of what Formstack sends when the fields are set up correctly:

.json payload

{
  "name": { "value": { "first": "John", "last": "Doe" } },
  "phone_number": { "value": "+18185551212" },
  "address": { "value": { "zip": "90210", "country": [ "US" ] } }
}

 

Adding the webhook in Formstack

Before you start, have your Community client ID and API token ready. 

  1. In Formstack, open the form you want to connect.
  2. Click Settings in the upper right corner.
    FS1.png
  3. In the left menu, select Email & Actions.
  4. Click Add a Webhook.
    FS2.png
  5. Enter the settings from the table below.

  6. Click Save Webhook.

     

Setting What to enter
Webhook Name Community Formstack Integration
Webhook URL https://api.community.com/webhooks/v1/formstack/<your_client_id>/form_submit_subscription_create?community_api_token=<token>
Checkboxes Check Post with sub-field names, Post with field type and Standardize field value types to be consistent
Post Data Field Key Post with internal field labels
Content Type JSON
File/Signature URL Type Authenticated URL (Default)

In the webhook URL, replace <your_client_id> and <token> with your own values, and leave out the < and >characters.

The webhook URL contains your API token, so keep it private. Anyone with the URL can access your account through the API.

Once the webhook is created, the integration is live. The next submission with a valid phone number triggers the welcome message.

 

Common questions

Why isn't my form data showing up in Community?

The most likely cause is a field label that doesn't match exactly.

Cause How to tell Fix
A field's internal label doesn't match The phone number comes through but other details are missing Check each label against the table in Setting up your form fields
The webhook isn't posting internal labels No fields come through as expected Set Post Data Field Key to Post with internal field labels. See Adding the webhook in Formstack
A webhook checkbox or setting is off A specific field is not coming through as expected Recheck every setting in Adding the webhook in Formstack
Gender identity value isn't one of the accepted values Gender identity is blank in Community Use only male, female, non-binary or no-answer as option values

 

Do I need to include every supported field?

No. Phone number is the only required field. Include any of the others you want, as long as each uses the right internal label.

 

Why didn't someone get a welcome message after submitting the form?

The welcome message is only sent when the submission includes a valid phone number. Check that the phone field uses the internal label phone_number and that the webhook is set up as described in Adding the webhook in Formstack. 

 

Is it safe to share my webhook URL?

No. The webhook URL includes your API token, which gives API access to your Community account. Treat it like a password. 

Related articles