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 shared contact list, in whose 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 list! 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 raw version of an HTML form with standard fields. You can change the visible input fields directly and send them to the selected end point by clicking the "Send" button. The result of the data transmission will then open in a new window. Here you can see in a JSON representation either the details of the created contact, or an error message, for example because the endpoint is not set to "active", or for example no receiving user list has been assigned.

In the HTML source code of "contact-form-template.html" you will find a code block that is commented-out. This is an exemplary collection of additional data. If you want to request and save additional information besides the standard fields, follow the instructions described in the comment block and the following section.

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 get correct date entries, you must first decide whether you want to

  1. transmit a simple date: this can be done in the form of common <input type='date' ...> or <input type='datetime-local' ...> elements, but it only works for use within the time zones UTC-11 to UTC+11. These transmission forms do not accept transmitted times. The latter are always taken as "at 12:00 noon, in time zone UTC+0".
  2. or if you need a complete, time zone based date and time, for which your form has to submit an ISO 8601 timestamp in UTC with offset 0

Valid Date Format

Example

Generates...

Valid range

Created with

yyy-MM-dd

2020-12-31

date only

UTC-11..UTC+11

<input type='date'>

yyy-MM-dd'T'hh:mm

2020-12-31T23:59

date only

UTC-11..UTC+11

<input type='datetime-local'>

yyy-MM-dd'T'hh:mm:ss

2020-12-31T23:59:59

date only

UTC-11..UTC+11

<input type='datetime-local'>

yyyy-MM-dd'T'HH:mm:ss.SSS'Z

2020-12-31T23:59:59.999Z

date and time

global

Date.prototype.toISOString()

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 eine empfangende geteilte Liste zu, in deren die Kontaktinformationen gespeichert werden sollen
  • stellen Sie sicher, dass der entsprechende Endpunkt aktiviert ist - nur aktive Endpunkte schreiben Kontaktdaten in die geteilte Liste der zugeordneten Benutzer! 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 mit Standardfeldern. Die sichtbaren Eingabefelder können Sie direkt verändern und per “Send”-Button testweise an den ausgewählten Endpunkt übermitteln. Daraufhin öffnet sich in einem neuen Fenster 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. keine empfangende Benutzer-Liste zugeordnet wurde.

Im HTML-Quelltext der “contact-form-template.html” finden Sie, in einem auskommentierten Quelltext-Block eine beispielhafte Erfassung von Zusatzdaten. Sofern Sie, neben den Standardfeldern noch weitere, eigene Informationen erfragen und speichern möchten, so folgen Sie den im Kommentarblock beschriebenen Answeisungen, sowie nachfolgender Sektion.

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. keine empfangende Benutzer-Liste 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, gilt es zunächst zu entscheiden, ob

  1. es Ihnen ausreicht, ein simples Datum zu übermitteln: dies kann in Form gängiger <input type='date' ...>- bzw. <input type='datetime-local' ...>-Elemente erfolgen, funktioniert allerdings nur für die Verwendung innerhalb der Zeitzonen UTC-11 bis UTC+11. Diese Übermittlungsformen übernehmen jedoch keine übermittelten Uhrzeiten. Letztere werden stets als “um 12:00 Uhr am Mittag, in der Zeitzone UTC+0” übernommen
  2. oder ob Sie ein vollständiges, und zeitzonengestütztes Datum samt Uhrzeit benötigen, wofür Ihr Formular jeodch einen ISO 8601 Zeitstempel in UTC mit Offset 0 übermitteln muss

Akzeptiertes Datumsformat

Beispiel

speichert

Gültig innerhalb

Erzeugt durch

yyy-MM-dd

2020-12-31

nur Datum

UTC-11..UTC+11

<input type='date'>

yyy-MM-dd'T'hh:mm

2020-12-31T23:59

nur Datum

UTC-11..UTC+11

<input type='datetime-local'>

yyy-MM-dd'T'hh:mm:ss

2020-12-31T23:59:59

nur Datum

UTC-11..UTC+11

<input type='datetime-local'>

yyyy-MM-dd'T'HH:mm:ss.SSS'Z

2020-12-31T23:59:59.999Z

Datum + Uhrzeit

weltweit

Date.prototype.toISOString()

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?