---
title: Embedded form JS API (draft) | Paperform Help Center | Paperform
description: You can listen for submission and page change events using our draft API.
url: "https://paperform.co/help/articles/embedded-form-submissions"
type: static
generatedAt: "2026-04-04T00:42:01.521Z"
---

Embedded form JS API (draft)
### Embedding

### This is a draft document, API subject to change.

## Submission Events

There are two ways to be notified of embedded Paperform submissions.

### 1. `onsubmit` attribute

You can add an attribute to the `div` of either of the following:

 - `onsubmit="myGlobalFunctionName"`
 - `data-onsubmit="myGlobalFunctionName"` (legacy)

So your embed code would look something like:

```html
<div data-paperform-id="contact-paperform" onsubmit="myGlobalFunctionName"></div>
<script>
  (function() {
    var script = document.createElement('script');
    script.src = "https://paperform.co/__embed";
    document.body.appendChild(script));
  })()
</script>
```

A global function by the name you use for `myGlobalFunctionName` will be called when the form is submitted.

It is passed a single argument which is an object with the following structure:

```javascript
{
  submission_id: "XXXXXXXXXX",
  total: null, // If there was a price processed
  data: [
    {
      title: "My Question Title",
      key: "xjsdjc", // Pre-fill key
      value: "Dean" // Answer for this question for this submission
    },
    ...
  ]
}
```

### 2. Event listener

Embedded forms also emit a custom event by the name of `PaperformSubmission` on submission, which can be listened to on the `div` from the embed, or on any parent element.

Details of the submission are located in `event.detail`.

#### Event listener example

```javascript
window.addEventListener('PaperformSubmission', function(e) { console.log(e) })
```

## Page Change Events

There are two ways to be notified of embedded Paperform page changes.

In either way, the page change event is triggered for page changes in both directions:

 - movement forward one page
 - movement backward one page

### 1. `onpagechange` attribute

You can add an attribute to the `div` of either of the following:

 - `onpagechange="myGlobalFunctionName"`
 - `data-onpagechange="myGlobalFunctionName"` (legacy)

So your embed code would look something like:

```html
<div data-paperform-id="contact-paperform" onpagechange="myGlobalFunctionName"></div>
<script>
  (function() {
    var script = document.createElement('script');
    script.src = "https://paperform.co/__embed";
    document.body.appendChild(script));
  })()
</script>
```

A global function by the name you use for `myGlobalFunctionName` will be called when the page is changed in the form.

It is passed a single argument which is an object with the following structure:

```javascript
{
    form_id: "form-id",
    currentPage: 1,
    totalPages: 35
}
```

### 2. Event listener

Embedded forms also emit a custom event by the name of `PaperformPageChange` when the page changes on the form, which can be listened to on the `div` from the embed, or on any parent element.

Details of the page change are located in `event.detail`.

#### Event listener example

```javascript
window.addEventListener('PaperformPageChange', function(e) { console.log(e) })
```

## How to use the PaperformSubmission Event with Google Tag Manager

No scripts are required in the form Analytics since we already push events to the parent website where the form is embedded.

### 1. Embed Code

The following code can be used on your website to push the submission_id, form_id and total amount to the dataLayer after the form is submitted.

Replace `your-form-id` with the actual form id:

```html
<div data-paperform-id="your-form-id" onsubmit="myGlobalFunctionName"></div>

<script>
  (function() {
    var script = document.createElement('script');
    script.src = "https://paperform.co/__embed.min.js";
    document.body.appendChild(script); })()
</script>

<script>
  function myGlobalFunctionName(event) {
    // Access the submission details
    const submissionId = event.submission_id;
    const formId = event.form_id;
    const total = event.total;
    console.log(submissionId, formId, total);

    // Push to the dataLayer
    try{
      var dataLayer = window.dataLayer || (window.dataLayer = []);
      if (event) {
        dataLayer.push({
          'event': 'PaperformSubmission',
          'submissionId': submissionId,
          'formId': formId,
          'total': total,
        });
      }
    }catch(e){}
  }
</script>
```

### 2. User-Defined Data Layer Variables

Add three User-Defined Data Layer Variables to your GTM container to capture the values that we push to the dataLayer.

![User-Defined Data Layer Variables](https://img.paperform.co/fetch/f_auto,w_1400/https://d3gw2uv1ch7vdq.cloudfront.net/img/screenshot-2024-02-09-at-2.27.44%E2%80%AFpm.png)

![Data Layer Variables configuration](https://img.paperform.co/fetch/f_auto,w_1400/https://d3gw2uv1ch7vdq.cloudfront.net/img/screenshot-2024-02-09-at-2.29.56%E2%80%AFpm.jpg)

### 3. Add Custom Event Trigger

Add the Trigger called “PaperformSubmission - ce” with a Trigger Type of Custom Event.

 - Event Name: `PaperformSubmission`
 - This trigger fires on **Event** that equals `PaperformSubmission`

![Custom Event Trigger](https://img.paperform.co/fetch/f_auto,w_1400/https://d3gw2uv1ch7vdq.cloudfront.net/img/screenshot-2024-02-09-at-2.35.09%E2%80%AFpm.png)

### 4. Add GA4 Configuration Tag

If you are currently sending data to GA4 with your GTM container, then skip this step since it is most likely already set up. Otherwise, here are the steps to add it to your GTM container:

 - Add the `GA4 Configuration` Tag
 - Tag Type: Google Analytics > Google Tag
 - Tag ID: the GA4 Measurement ID

 - from GA4 Admin > Data Collection & Modification > Web Stream Details > Measurement ID
 - Trigger: All Pages

![](https://img.paperform.co/fetch/f_auto,w_1400/https://d3gw2uv1ch7vdq.cloudfront.net/img/screenshot-2024-02-09-at-2.41.57%E2%80%AFpm.png)

### 5. Track conversions with a GA4 Event tag

The following tag captures conversions when your form is submitted and sends the values from the dataLayer as event parameters to GA4. Once you see the custom event in your Google Analytics (within 24 hours), you can change it to a conversion event.

 - Add the `GA4 - PaperformSubmission` Tag
 - Tag Type: Google Analytics: GA4 Event
 - Tag ID: the GA4 Measurement ID
 - Event Parameters

 - formID value is {{dlv - formId}}
 - submissionId value is {{dlv - submissionId}}
 - total value is {{dlv - total}}
 - Trigger: `PaperformSubmission - ce`