Form Rest API – Help Center

Form Rest API is a service that allows to execute magnews' frontend form submission through AJAX.

This is useful to integrate external web pages with magnews features. With a proper contact token, it is also possible to execute a form submission accessing or manipulating a contact's data (depending on the post submit actions included in the form).

In order to execute a form submit you need:

a custom hostname for the customer account (in this page we will use "customerhost.com"). Form rest API is available at http://customerhost.com/nl/api/forms
the form object ID (eg: 971)
the form input parameters name attributes.
at least a form submit button name attribute.

A form submission must be sent using JSON format in a POST request body.

Property	Datatype	Description
`idform`	int	Required. The form object ID
`language`	string	Optional. Language code (3 characters) used for error messages.
`token`	string	Optional. Token identifying the contact. If no token is provided, form submission will be anonymous.
`parameters`	array of Object	Required. Each object represents a single input. Remember to include an object representing a submit button. Note The input field name is auto generated by magnews, but can be overridden in the "Advanced" tab of the input field edit page, section "Scripts options".

The example below shows a POST request body for a generic form without a contact token and the respective response:

// Request body
{
    "idform":432,
    "language":"ENG",
    "parameters":[
        {
           "name":"overridden_input_name",
           "value":"123"
        },
        {
           "name":"_mn_form_ctrl_5782", // auto generated input name
           "value":"I am an input value"
        }
    ]
}

// Response body
{
    "ok": true
}

How to obtain a contact token

A contact token can be obtained in three ways:

Using a post submit action which inject a contact identity in the form context, like "Subscribe contact" or "Contact login".
Obtaining it from a webtracking script.
In Apps, by getting the value of the field token from the Contact bean (previously retrieved by using functions like findContactById, findContactByPrimaryKey etc).

Obtain a contact identity through form submit

The example below shows a POST request body for a subscription form and the respective response:

    // Request body
{
    "idform":123,
    "language":"ENG",
    "parameters":[
        {
           "name":"_mn_form_ctrl_153", // auto generated input name
           "value":"I am an input value"
        },
        {
           "name":"overridden_email_input_name",
           "value":"example@mydomain.com"
        }
    ]
}

// Response body
{
    "idcontact": 4129578,
    "ok": true,
    "token": "17beg3f032ag30e09281398788d25f28688480e2481a18ac432a"
}

Once a token has been retrieved, it can be used for further form submissions with the contact identity set. The example below shows a POST request body for a generic form with a contact token:

    {
    "idform":432,
    "language":"ENG",
    "token":"17beg3f032ag30e09281398788d25f28688480e2481a18ac432a",
    "parameters":[
        {
           "name":"overridden_input_name",
           "value":"update value"
        },
        {
           "name":"_mn_form_ctrl_5782", // auto generated input name
           "value":"I am an input value"
        }
    ]
}

Obtain a contact identity through web tracking

If web tracking script is included in an external web page, it's possible to ask the contact token through the mna.getContactId() function.
In order to get the real ID contact value you can use the mna.getTrackedContactId() function instead, which it tries to retrieve the ID contact from the token, returning 0 if it can't. You can use this function like that: mna.getTrackedContactId(mna.getContactId()).
Note that the webtracking script is loaded asynchronously, so the mna.getContactId() function could not have been declared and, even if a contact session is present, it could not be retrievable.
Furthermore, mna.getContactId() can return null if no session has been started.

    <!DOCTYPE html<br />
<html>
    <head>
        <title>TODO supply a title</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script type="text/javascript">
            (function (m, a, g, n, e, w, s) {
                m[e] = m[e] || function () {
                    (m[e].q = m[e].q || []).push([arguments[0], arguments[1], 1 * (new Date()).getTime()]);
                };
                w = a.createElement(g), s = a.getElementsByTagName(g)[0];
                w.async = 1;
                w.src = n;
                s.parentNode.insertBefore(w, s);
            })(window, document, 'script', '//customerhost.com/webtracking/js/webtracking.js', 'mna');
            mna('init', {sendbeacon: true, apikey: '17begbfa4a6f', trackerhostname: 'customerhost.com', sessionTimeout: 20});
        </script>
    </head>
    <body>
        <a href="javascript: void(0)" onclick="submitWithContactIdentity()" />
        <script type="text/javascript">
            function submitWithContactIdentity() {
                if (!mna.getContactId) {
                    // webtracking.js is loaded asynchronously, so the mna.getContactId function could not have been declared at this time.
                    return;
                }
                var contactId = mna.getContactId();
                if (!contactId) {
                    // contactId can be null if no session has been started.
                    return;
                }

                [..]
                Do your AJAX request
            }
        </script>
    </body>
</html>