Connecting web forms

Web2Lead is the snapADDY's new lead-generation-tool.

It automatically adds the visitors of a contact form (e.g. on the homepage of your company) to a contact list in the snapADDY Grabber. Once the contact information is exported to the Grabber, these leads can be enriched with contact information and company data (and finally exported to your CRM system).

Procedure

1. Create a data-export destination

First you need an endpoint to which you can transmit the information entered in your company's contact form.

As snapADDY admin, first open your profile in your dashboard and then go to "Organisation" → "Contact Forms".

Under "Add form" you can then open an interface to create the necessary data acceptance endpoint.

Setting the end point:

  • assign a meaningful name to the endpoint to be able to understand its purpose later
  • additional information can be optionally entered in the comment field
  • Assign a receiving user, in whose Grabber contact list the contact information should be stored
  • make sure that the corresponding endpoint is activated - only active endpoints write contact data into the grabber of the assigned user! Inactive forms do not accept any data, and answer corresponding transmission attempts
  • create the contact form by clicking the "Create form" button

This will update your view and two additional form fields will appear.

2. Copy the address of the data-export destination

In the updated view, the "Target URL" field contains the Internet address of the endpoint to which your form must submit its own data via POST request. Please copy this address to include it in the HTML source code of your form.

3. Optional: copy and adapt form template

If you do not have HTML code for a form yet, you can copy a template from the "HTML Code" field:

  • Click on the "Copy" button at the end of the line
  • Open a text editor
  • Paste the copied template
  • Save the file as e.g. "contact-form-template.html"
  • Open the saved file in your browser

In the page that appears, you will see the unrefined HTML form. This also includes further export examples to query additional data. These are just examples. If you you want to query the additional fields from the example, you would have to configure those fields first in your organization settings (mapping).

To be able to try out the form right away, you can simply remove the additional fields. To do this, simply delete the lines in the HTML template that are marked from START to END:

<!-- examples of custom-fields START, need to be configured in your own organization's settings, can be removed --> ... <!-- examples of custom-fields END, need to be configured in your own organization's settings, can be removed -->

After you have modified the HTML form as desired, you can save the file again and reload the form in your internet browser. Now you can see the updated form and send the data to your selected end point by clicking the "Send" button.

The result of the data transmission will now open in a new window. Here you can see in a JSON representation either the details of the created contact, or an error message. One reason for an error could be that the endpoint is not set to "active", or no receiving user has been assigned.

4. Optional: connect your own data types (customFields)

If you want to get more than the standard information, you can customize your webform further. In our mapping documentation you can see the structure of the different types of fields (e.g. text, select, multiselect...)

Additional fields, so-called "customFields" must be included in the mapping of your organization.

If your snapADDY organization runs on the standard-mapping, i.e. snapADDY was not commissioned to create an individual mapping for your organization, you can just work with the standard fields of the web form (see 3.).


With a custom mapping for your organization, you can find mapped customFields in your organization's mapping settings. Of course, you can always ask your snapADDY contact person.

When it comes to working with customFields, a few basics are crucial to understand:

4.a Form elements and customFields

To properly address your fields, always use the id of a customField as name attribute of the respective form element. This is how they are defined in your mapping:

{ "customFields": [ 
{
"id": "c_description",
"label": {
"DE": "Beschreibung",
"GB": "Description",
},
"properties": {
"defaultValue": ""
},
"type": "INPUT"
}
]
}

In your HTML form you must then translate the customFields as follows:

<input name="c_description" type="text" id="Description">

The name attribute is the determining factor, when it comes to the values being exported correctly, while the id attribute can be used arbitrarily.

Communication details

Export formats

Receiving data on the server side can be done via two formats:

  • as application/x-www-form-urlencoded, which is the standard behavior of HTML forms without further enctype-specification, which data are stored:
firstName=Max&lastName=Mustermann&email=m.mustermann%40snapaddy.com&organization=snapADDY+GmbH&companySize=1-10

  • in a JSON format in the request body:
{ 
"firstName": "Max",
"lastName": "Mustermann",
"email": "m.mustermann@snapaddy.com",
"organization": "snapADDY+GmbH",
"companySize":
"1-10"
}

Details of possible server responses with regard to contact information, submitted by webforms can be found in the reference to the Swagger API, where you can also experiment with the relevant requests directly.

Validation checks

In order to spare you from incorrect contact information in the Grabber, we check:

  • that non-empty, e-mail addresses are theoretically valid
  • that transmitted dates are valid, e.g. that they are not dated February 35, 2020
  • that values for customFields are also valid according to your specifications, (e.g. that no picklist choice is transmitted which is not actually part of your picklist values)

Date format

To receive date information, the webform must send the date-values in the following format:

YYYY-MM-DDTHH:MM:SS.mmmZ

From left to right the date is composed like this:

  • YYYY the year as a four-digit number
  • MM the one-based month (01=January, 12=December)
  • DD the one-based tag (01)
  • a T as separator
  • HH the zero-based number of hours
  • MM the zero-based minute number
  • SS the zero-based number of seconds
  • . as separator
  • three digits of a zero-based millisecond number
  • a Z

Example: 2020-12-31T23:59:59.999Z as last day in December, last date before the new year begins.

FAQ

Do I need one endpoint per contact form?

No, you can use an already existing endpoint for as many forms as you like.

What happens to contacts that are sent to inactive endpoints?

The endpoint refuses to accept the contact data and terminates the network request with error 404, "Not found". No contact data is written to the grabber.

I have deleted my Endpoint accidentally - what now?

If you have deleted an endpoint by mistake, please contact snapADDY support. We will be able to restore the endpoint for you.

Further references

  • list of all possible standard fields for forms: here you can see for which kind of information values can be submitted - you can use the listed names directly as name attribute for form elements in your contact form
  • Documentation of the network details, as well as Swagger API to try out the network requests in JSON format: here you don't need a form, but can simply provide the desired information as JSON data, JSON template included.
  • Instructions for creating your own data types: if our standard modules are not sufficient for you, for example, because you want to inquire about product interests etc., you will find instructions here to allow further response options and additional information in your contact form, which will be saved directly with the Grabber contacts.

_________________________________
(German version)

Webformulare anbinden

Web2Lead ist das neue Kundengewinnungstool von snapADDY.

Damit werden die Besucher eines Kontaktformulars (z.B. auf der Homepage Ihres Unternehmens) automatisch zu einer Kontaktliste im snapADDY Grabber hinzugefügt. Einmal im Grabber gelandet, können die Leads mit Kontaktinformationen und Firmendaten angereichert und schließlich in Ihr CRM-System exportiert werden.

Vorgehensweise

1. Ziel der Datenannahme anlegen

Zunächst benötigen Sie einen Endpunkt, an den Ihr Kontaktformular am Ende die eingegeben Informationen übermitteln kann.

Öffnen Sie, als Administrator im snapADDY Dashboard, zunächst Ihr Profil, und klicken dann unter “Organisation” auf den Menüpunkt “Kontaktformulare”.

Unter “Formular hinzufügen” können Sie dann eine Maske zur Anlage des notwendigen Datenannahme-Endpunkts öffnen.

Einstellung des Endpunkts:

  • vergeben Sie einen aussagekräftigen Namen für den Endpunkt, um dessen Zweck später auch später noch nachvollziehen zu können
  • in das Kommentarfeld können optional noch zusätzliche Informationen eingetragen werden
  • ordnen Sie einen empfangenden Benutzer zu, in dessen Grabber-Kontaktliste die Kontaktinformationen gespeichert werden sollen
  • stellen Sie sicher, dass der entsprechende Endpunkt aktiviert ist - nur aktive Endpunkte schreiben Kontaktdaten in den Grabber des zugeordneten Benutzers! Inaktive Formulare nehmen keine Daten entgegen, und beantworten entsprechende Übermittlungsversuche
  • legen Sie das Kontaktformular durch Klicken des “Formular erstellen”-Knopfes an

Daraufhin aktualisiert sich ihre Ansicht, und zwei zusätzliche Formularfelder erscheinen.

2. Adresse der Datenannahme kopieren

In der aktualisierten Ansicht finden Sie im “Ziel-URL”-Feld die Internet-Adresse jenes Endpunkts, an den Ihr Formular die eigenen Daten per POST-Request übermitteln muss. Diese kopieren Sie bitte, um sie in den HTML-Quelltext Ihres Formulars zu übernehmen.

3. Optional: Formularvorlage kopieren und anpassen

Sofern Sie noch keinen HTML-Quelltext für ein Formular haben, so können Sie sich aus dem “HTML Code”-Feld eine Vorlage kopieren:

  • Klicken Sie auf den “Kopieren”-Knopf am Ende der Zeile
  • Öffnen Sie einen Text-Editor
  • Fügen Sie die kopierte Vorlage ein
  • Speichern Sie die Datei als z.B. “contact-form-template.html”
  • Öffnen Sie die gespeicherte Datei in ihrem Browser

In der daraufhin dargestellten Seite sehen Sie die Rohfassung eines HTML-Formulars. Das darstellte Formular umfasst jedoch, als umfangreicheres Beispiel, auch die Abfrage von Zusatzdaten, deren Verfügbarkeit Sie zunächst in Ihren Organisationseinstellungen konfigurieren müssten.

Um das Formular dennoch direkt ausprobieren zu können, können Sie die Felder für die Zusatzdaten einfach entfernen. Löschen Sie hierfür in der HTML-Vorlagen einfach jene Zeilen, welche von START bis END markiert sind:

<!-- examples of custom-fields START, need to be configured in your own organization's settings, can be removed --> ... <!-- examples of custom-fields END, need to be configured in your own organization's settings, can be removed -->

Sofern Sie die Datei erneut speichern, und die Formulardarstellung im Internet-Browser neu laden, können Sie durch Klick auf den “Send”-Button das Formular testweise an den ausgewählten Endpunkt übermitteln.

In einem neuen Fenster öffnet sich nun das Ergebnis der Datenübermittlung. Hier können Sie in einer JSON-Darstellung entweder die Details des erstellten Kontakts sehen, oder die eine Fehler-Darstellung, beispielsweise, weil der Endpunkt nicht auf “aktiv” gestellt ist, oder z.B. kein empfangender Benutzer zugeordnet wurde.

4. Optional: Eigene Datentypen anlegen (customFields)

Sofern Ihnen die Standard-Informationsbausteine nicht ausreichen, finden Sie unter “Weiterführenden Verweise” Hilfestellung, um eigene Auswahllisten, Datumsangaben, Freitextangaben und ähnliches zu erfassen.

Weitere Felder, so genannte "customFields" müssen sich dem Mapping Ihrer Organisation wiederfinden. Wenn bei Ihnen das Standard-Mapping hinterlegt ist, also kein individuelles Mapping bei snapADDY beauftragt wurde, können Sie nur mit den Standardfeldern des Webfomulars arbeiten (siehe 3.).

Die Mapping-Einstellung für Ihre Organisation, und damit Ihre customFields, können Sie in den Firmeneinstellungen nachvollziehen, oder fragen Sie einfach Ihren zuständigen snapADDY Ansprechpartner.

Im Zusammenspiel mit den customFields sind ein paar Grundlagen elementar wichtig zu verstehen:

4.a Benennung von customFields und Formular-Elementen

Verwenden Sie stets die id eines customFields als name-Attribut des betreffenden Formular-Elements. Sehen Sie nachfolgend ein Beispiel, wie customFields im Mapping erscheinen:

{ "customFields": [ 
{
"id": "c_description",
"label": {
"DE": "Beschreibung",
"GB": "Description",
},
"properties": {
"defaultValue": ""
},
"type": "INPUT"
}
]
}


In Ihrem HTML Formular müssen Sie die customFields dann wie folgt üersetzen:

<input name="c_description" type="text" id="Beschreibung">

Das name-Attribut ist entscheidend für die Zuordnung der zu speichernden Werte, während das id-Attribut beliebig nutzbar ist.

Kommunikationsdetails

Übermittlungsformate

Die Datenannahme auf Serverseite kann über zwei Formate erfolgen:

  • als application/x-www-form-urlencoded, als Standardverhalten von HTML-Formularen ohne weitere enctype-Angabe, welche Daten in
firstName=Max&lastName=Mustermann&email=m.mustermann%40snapaddy.com&organization=snapADDY+GmbH&companySize=1-10
  • als JSON-Daten im Body des Requests:
{ 
"firstName": "Max",
"lastName": "Mustermann",
"email": "m.mustermann@snapaddy.com",
"organization": "snapADDY+GmbH",
"companySize":
"1-10"
}

Details zu möglichen Serverantworten, auf die von Formularen übermittelte Kontaktdaten, finden Sie unten, im Verweis auf die Swagger-API, über welche Sie die betreffenden Requests auch direkt ausprobieren können.

Gültigkeitsprüfungen

Um Ihnen fehlerhafte Kontaktinformationen im Grabber zu ersparen, überprüfen wir

  • dass nicht-leere, übermittelte E-Mail-Adressen theoretisch gültig sind
  • dass übermittelte Datumsangaben gültig sind, also z.B. nicht auf den 35. Februar 2020 lauten
  • dass übermittelte customFields-Werte auch gemäß ihren Vorgaben gültig sind, also z.B. dass für Auswahlmöglichkeiten nichts übermittelt wird, was Sie gar nicht zur Auswahl gestellt haben

Datumsformat

Um Datumsangaben entgegen zu nehmen, muss das Formular die betreffende Datumsangabe in folgendem Format übermitteln:

YYYY-MM-DDTHH:MM:SS.mmmZ

Von links nach rechts setzt sich die Datumsangabe so zusammen:

  • YYYY das Jahr als vierstellige Zahl
  • MM der einsbasierte Monat (01=Januar, 12=Dezember)
  • DD der einsbasierte Tag (01)
  • ein T als Trennzeichen
  • HH die nullbasierte Stundenzahl
  • MM die nullbasierte Minutenzahl
  • SS die nullbasierte Sekundenzahl
  • ein . als Trennzeichen
  • drei Ziffern einer nullbasierten Millisekundenzahl
  • ein Z

Beispiel: 2020-12-31T23:59:59.999Z als letzter Tag im Dezember, letzter Moment zum Jahreswechsel.

FAQ

Brauche ich je Kontaktformular einen Endpunkt?

Nein, Sie können einen angelegten Endpunkt für so viele Formulare verwenden wie Sie möchten.

Was geschieht mit Kontakten, die an inaktive Endpunkte übermittelt werden?

Der Endpunkt verweigert die Annahme der Kontaktdaten, und beendet die Netzwerkanfrage mit einem Fehler 404, “Nicht gefunden”. Es werden keine Kontaktdaten in den Grabber geschrieben.

Endpunkt versehentlich gelöscht - was nun?

Sofern Sie einen Endpunkt versehentlich gelöscht haben sollten, so wenden Sie sich bitte an unseren Support, dann können wir den betreffenden Endpunkt für Sie wiederherstellen.

Weiterführende Verweise

Did this answer your question?