Post to the Paminga Form Handler
If you have a non-Paminga form on your website that you do not want to replace with a Paminga Form, but would like to trigger automated actions in Paminga whenever that form is submitted, posting to our Form Handler is a great long-term solution.
The Basics
When a web form is submitted, that form “posts” its submitted values to a URL.
When that "post" is received at the URL, some code reads the values that were submitted in the form, and takes action – like sending an email notifying people that the form was submitted.
But a web developer can easily have that form submission "posted" to more than one URL – they can "post" that form submission to Paminga's "form handler" as well.
Paminga will treat it just like the submission of any Paminga form which means you can trigger any number of automations in Paminga based on submissions of non-Paminga forms.
Use Case
If you have customized or highly complex forms that you do not want to change or replace with a Paminga form, we created this solution for you.
By posting submissions to the Paminga form handler, you can leave your existing forms in place and continue to create more of them as needed, while taking full advantage of Paminga automation capabilities.
Setup
First, you’ll create a Form in Paminga to which you’ll send your form submissions. You do not need to publish this form on your website. It exists only to accept submissions, map submitted values to Paminga standard and custom fields, and trigger automated actions upon submission.
Then, when your non-Paminga form is submitted, post to the Paminga form handler the fields you want Paminga to absorb.
Paminga will:
- See a submission of the Paminga form you created even though the form was never published anywhere
- Create or update a Contact in Paminga
- Track a conversion
- Make an entry in the Activity Stream
- Trigger all actions you’ve chosen on the Form Actions tab
The Endpoint
Post your submissions to:
POST https://api.paminga.com/api/form-submission-handler
The handler expects a JSON body (Content-Type: application/json) with two things:
id— your Paminga Form's ID (a number)submissionValues— an object of{ "Element Name": value }pairs, one entry per field you want Paminga to absorb
Everything else is optional. A minimal post looks like this:
{
"id": 1234,
"submissionValues": {
"email_address": "person@example.com",
"first_name": "Jane",
"last_name": "Doe"
}
}
You do not have to send over every field. The one field you really want inside submissionValues is the value for whichever field you’ve mapped to Email Address on your Paminga form — that’s how Paminga creates or matches a Contact.
If your Paminga account is hosted in the EU, post to https://api.eu.paminga.com/api/form-submission-handler instead. Everything else on this page is identical.
Details
Step 1: Create a form in Paminga
- This form will include all field values in which you would like collect in Paminga
- If you would like to map these fields in Paminga, please choose which fields to map each value to
- Have a custom field on this form you would like to map to Paminga? Create a new Custom Field to catch this data
- Set up any Form Actions would you like to take place when this form is submitted, such as “Modify List Membership” or “Send Autoresponder Email”
Step 2: Change each form field’s Element Name under the Advanced Tab of the Paminga form to match the label for each field from the form on your site.
The keys you send inside submissionValues must match the Element Name of each corresponding field on your Paminga form. Matching those two up is the whole trick — get the names right and Paminga maps every value to the correct field automatically.
- Not sure what the field labels are or where to find them?
- Inspect the page on which your form is present. From here, hover over each form field to display their “field-name”
- Once you have the labels for each field, under the Advanced Tab for each form field you would like to track in Paminga, update the Element Name to match the field label from your form
Step 3: Via the Forms URL in Paminga, locate your Form ID.
- This is the
idyou’ll send in the payload so Paminga knows which form owns the data - You will see this located after the ? in the URL of the form builder when viewing the form.
Step 4: Have your Web Developer post your form fields to Paminga.
Below you will find an example of how to accomplish this. That being said, this example is not to be taken and used as-is on your website, as we do not know if it will work on your website.
You will need a web developer on your side to review this example and implement it using whichever syntax/language works with your website. This example is simply a guide for a web developer to understand what they need to do.
You don’t send any visitor-tracking data yourself. As long as your form posts from a page running the Paminga tracking beacon, the beacon adds the visitor and campaign context automatically (see below). So the code your developer needs is just a plain post of your form’s fields:
<script>
// Post your form's values to Paminga. The tracking beacon already on the page
// adds the visitor and campaign context automatically — you don't handle it here.
async function postToPaminga() {
var payload = {
id: 1234, // Your Paminga Form ID
submissionValues: {
// Each key must match the Element Name of the corresponding field on your
// Paminga form. Replace the placeholder values with your form's real values.
email_address: "REPLACE_WITH_EMAIL_ADDRESS",
first_name: "REPLACE_WITH_FIRST_NAME",
last_name: "REPLACE_WITH_LAST_NAME",
},
};
await fetch("https://api.paminga.com/api/form-submission-handler", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
});
}
// Call postToPaminga() when your own form is submitted — typically alongside
// (or just after) whatever your form already does.
</script>
When your form posts from a page running the Paminga tracking beacon, the beacon adds the following to your submissionValues (plus a top-level url) automatically — only when you haven’t set them yourself:
__mauuid— the visitor’s ID, tying the submission to their tracked activity__acuuid— the email send that drove the visit, when there was one__pcs— the emailed contact’s identity, when they arrived from an email link__url_params— UTM parameters and click IDs, for campaign attribution
Automatic injection only happens for a browser fetch / XMLHttpRequest post with a JSON body, on a page where the beacon is loaded. Server-side posts, non-JSON request bodies, and pages without the beacon receive none of it — in those cases, pass whatever you need yourself (see Setting Values Yourself).
Step 5: Place the code with your fields and values on your site.
Once in place, any submission on your site where this code runs — along with the Tracking Beacon — will be sent to Paminga.
Sending Values as Text
The form handler accepts dropdown, event registration, and subscription list values as plain, human-readable text — you don’t have to look up Paminga’s internal IDs first.
Post the label a person would recognize and Paminga resolves it for you:
- Dropdowns / multiselects — the option’s label (e.g.
"Restaurateur"), or an array of labels for a multiselect - Event registration — the event’s name
- Subscription management — the subscription list’s name
If a value matches nothing, Paminga keeps the submission and passes the value through untouched rather than rejecting it — so a single typo never costs you the whole submission.
Setting Values Yourself
Every value the beacon adds can also be set by hand, and Paminga never overwrites a value you provide. This is how you attach tracking from a server-side integration, where there’s no beacon on the page to do it for you. Add them inside submissionValues (except url, which sits at the top level):
{
"id": 1234,
"submissionValues": {
"email_address": "person@example.com",
"__mauuid": "b3f1c2a4-9d8e-4a1b-8c7d-0e1f2a3b4c5d",
"__acuuid": "9a1c7d2e-1f3b-4c5d-8e9f-0a1b2c3d4e5f",
"__pcs": "eyJpdiI6Ii4uLiIsInZhbHVlIjoiLi4uIn0=",
"__url_params": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring_sale",
"utm_term": "running shoes",
"utm_content": "hero_cta",
"gclid": "Cj0KCQ..."
},
"__contactid": 84213
},
"url": "https://yoursite.com/pricing"
}
__mauuid— the visitor’s Paminga ID (the value from the tracking-beacon cookie). Ties the submission to that visitor’s tracked activity.__acuuid— the ID of the email send that drove the visit, when there was one.__pcs— the emailed contact’s identity, present when they arrived from an email link.__url_params— an object of UTM parameters and ad click IDs. Paminga keeps the allowed keys:utm_source,utm_medium,utm_campaign,utm_term,utm_content, and the click IDsgclid,gbraid,wbraid,fbclid,msclkid,ttclid,li_fat_id,twclid.__contactid— a known Paminga contact’s numeric ID. Binds the submission directly to that contact. It’s honored only when that contact belongs to the same account as the form, and it takes precedence over email matching.url— set at the top level, outsidesubmissionValues: the page the form was submitted on.
Again, if any questions arise on this, please reach out to support@paminga.com and a member of our Customer Success Team will be happy to help.
