Skip to content

// forms and surveys

Via API

Formstack email verification with pingutil

Formstack submissions often drive approvals, document generation and CRM records, so an unreachable email breaks the process further down the line. A Formstack webhook set to JSON can post each submission to a small service that verifies the address with pingutil and forwards valid contacts or flags the rest. The webhook fires after submission, so this filters records; it cannot block the form.

Where it connects: Formstack Forms webhook ("Send Data to an External URL") with JSON content type and HandshakeKey

What goes wrong without it

  • Our intake form starts a whole approval workflow and then the applicant never receives the decision email.
  • Sales ops cleans bounced contacts out of Salesforce every month and most came from Formstack.
  • We have no way to tell a student or personal address from a company one on our partner form.

What you can do with Formstack and pingutil

  • Verify applicants before workflows send documents

    Check the address first, then forward valid submissions to the system that sends contracts or decisions. Invalid ones go to a queue for staff to follow up by phone.

  • Label personal, education and government addresses

    Call /v1/lookup with skip_enrichment to add category (company, free, educational, government) so intake teams route each submission correctly.

  • Attach company data to partner sign-ups

    For company domains, a full lookup returns the company profile, which you can pass to the CRM alongside the submission.

Set it up

  1. 1

    Create a pingutil key and set PINGUTIL_KEY and FORMSTACK_HANDSHAKE_KEY in your service environment.

  2. 2

    In Formstack, open the form Settings, then Emails & Actions, and add a webhook ("Send Data to an External URL") pointing at your service.

  3. 3

    Choose JSON as the content type, pick API-friendly field names for the field keys, and set a shared secret (sent as HandshakeKey).

  4. 4

    Deploy the Flask handler below and adjust the email key to match your field's API-friendly name.

  5. 5

    Submit a test entry and confirm the service logs the HandshakeKey check and the pingutil status.

Flask receiver for Formstack JSON webhooks
import hmac
import os

import requests
from flask import Flask, request

app = Flask(__name__)
PINGUTIL_KEY = os.environ["PINGUTIL_KEY"]


def verify(email: str):
    try:
        r = requests.post(
            "https://pingutil.com/v1/verify",
            json={"email": email},
            headers={"Authorization": f"Bearer {PINGUTIL_KEY}"},
            timeout=10,
        )
        return r.json() if r.status_code == 200 else None
    except requests.RequestException:
        return None  # fail open


@app.post("/webhooks/formstack")
def formstack():
    body = request.get_json(force=True, silent=True) or {}
    if not hmac.compare_digest(str(body.get("HandshakeKey", "")), os.environ["FORMSTACK_HANDSHAKE_KEY"]):
        return "forbidden", 403

    email = (body.get("email") or "").strip()  # API-friendly key of your email field
    if not email:
        return "ok"

    result = verify(email)
    record = {
        "formstack_submission_id": body.get("UniqueID"),
        "email": email,
        "email_status": result["status"] if result else "unchecked",
        "email_reason": result["reason"] if result else None,
        "did_you_mean": result.get("did_you_mean") if result else None,
    }

    if result and result["status"] == "invalid":
        requests.post(os.environ["REVIEW_QUEUE_URL"], json=record, timeout=10)
    else:
        requests.post(os.environ["CRM_WEBHOOK_URL"], json=record, timeout=10)
    return "ok"

What to do with each result

pingutil resultAction in Formstack
status: "valid"Forward to the CRM or the next workflow step.
status: "invalid"Send to a review queue instead of the workflow.
status: "risky"Forward with the status so staff know a reply is not guaranteed.
category: "educational" or "government"Route to the right intake team.
did_you_mean is setShow the suggestion to staff in the review queue.

Limits to plan for

  • The webhook fires after Formstack has saved the submission. pingutil cannot stop the submit or change the stored entry.
  • The HandshakeKey is a shared secret sent in the body, not a signature. Formstack also offers HMAC signing if you need to verify payload integrity.
  • Formstack does not document a webhook timeout in the pages we checked. If your workflow is time-sensitive, answer first and verify in a background job.

Formstack documentation

Formstack is a trademark of its owner. This integration uses Formstack's documented extension points; it is not an official Formstack app.

Common questions

How are fields named in a Formstack JSON webhook?
That depends on the field key setting on the webhook: field names, field IDs, API-friendly names or internal labels. Pick one and match it in your handler.
Can Formstack reject a submission based on my webhook response?
No. The webhook only receives data after submission, so use it to filter what reaches the next system.

Stop bad addresses in Formstack today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Formstack setup will receive.