Docs

Manual on how to use the service

Creating a form

After you sign up (or sign in) you will be redirected to the 'Forms' page. To create a form it is enough to click on the 'Add form' button.

After new form is created you will be redirected to the 'Settings' tab of the form page.

Form configuration

Here is a form parameters description:

  • Name - this is a form name used on the website only for listing purposes.
  • Description - this is the form description for you.
  • Subject - this is the text for a submission notification email subject. You can use {{Request_ID}} variable that will be substituted with the corresponding value.
  • Thank you message - this is the message user will see after he submits the form. This functionality works only if you leave 'Redirect to URL' field empty. If you are submitting your form via AJAX request the system will return the message in its response.
  • Redirect to URL - URL of a page where you want the user to be redirected upon successful form submission. If you are submitting the form via AJAX request the system will return the URL in its response.
  • Submit to email - Enter your email address here if you want to receive form submissions to your email.
  • Submit to URL - Enter URL of a web service that can accept POST requests. Our system will POST JSON data upon each form submission to the provided URL. See details below.
  • Allowed referrers - We recommend you to enter here the URL(s) of your website(s) where your form is located to avoid getting submissions from unwanted places.
  • Apply changes (publish the form) after saving them - check it if you want to make the form changes available in the form API entrypoint right away after form is saved.

After the form saved and published it is ready to accept submissions. At this point, everything you submit will be saved in our database without any verification.

Form fields configuration

If you want to verify data user enters and submits you need to add fields configuration on the 'Fields' tab of the form page.

Click on the 'Add field' button. A new field form will appear in the table below.

Here is a field properties description:

  • Name - here you should enter the name you used in your name attribute of <input>
  • Type - select type of data you expect from a user. Supported data types are:
    • Text - any string;
    • Number - a number (1, 2, 3, ... as well as 3.14, etc);
    • Date - a date in the format YYYY-MM-DD. For example, January 23rd, 2019 will be 2019-01-23;
    • Time - time in the format HH:MM[:SS] or h:mm a. Examples of right format are: 13:34 or 1:34 PM, 14:21:34 or 2:21:34 PM;
    • Date Time - date and time together. For example, 2019-01-23 13:56:12 or 2019-01-23 1:56:12 PM;
    • Phone - the string represents a phone number. A user can enter '-' and spaces, '+' and digits. Examples: +1 800 123 1234, 800-123-1234, (800) 123 1234, 8001231234, +18001231234;
    • Email - the string represents an email address. First encountered email field (alphabetical order) will be used as 'Reply To' in a submission email notification;
    • Url - the string represents a URL address;
    • Boolean - the string that can only accept values 'true' or 'false';
    • Match to Reg. Expression - a regular expression to run against user input. Enter regular expression in the 'Options' input;
    • Select - user's input should match one of the options for the field. Enter comma separated list of allowed values in the 'Options' input. It is case insensitive;
    • AntiSpam - special type (honeypot) for tricking spambots. See the details below;
    • ReCaptcha v2 - special type for working with Google ReCaptcha. Default field name should be 'g-recaptcha-response' unless you customized reCaptcha front-end part. In the 'Options' input enter reCaptcha's secret key.
    • File - a file. In the 'Options' field you can specify a regular expression for file extensions to accept. For example, '(pdf|doc|docx)$' will accept only PDF, and MS Words files extensions. To accept images only, the 'Options value should be '(jpg|jpeg|png)$'
  • Label - this is the field label. The information will be used to show a user field name where there are errors.
  • Is the field required - check it if you want the field to be required.
  • Min. value - for numbers this is min allowed value, for string types, this is min allowed length of the string. For files, this is min allowed file size in bytes.
  • Max. value - for numbers this is max allowed value, for string types, this is max allowed length of the string. For files, this is max allowed file size in bytes. File size can not be more than can not be more than 20 971 520 bytes (20 MB).
  • Options - For the field type 'Match to Reg. Expression' this is a regular expression (e.g.: '^([0-9]{9}-[A-Za-z]{3})$'). For the field type 'File' this is a regular expression for file extension. For the field type 'Select' this is a coma separated list of options for select field type (ex: 'orange,banana,pineapple').

When you added all the fields you need to click on the 'Apply changes' in the tab toolbar or on the 'Forms' page as otherwise these new or updated fields will not be used.

Creating a form on your website

Note that the URL where you need to submit data is located on the 'Settings' tab of the form page right above the form properties.

Here is an example of a form you may create on your website:

<form id="contact-form" action="http://api.formsubmits.com/forms/1135921e-c7db-48c3-85d0-3b9b6d8e855c/submit" method="POST">
    <fieldset>
        <div>
            <label>Name</label>
            <input type="text" name="name" />
        </div>
        <div>
            <label>Email</label>
            <input type="email" name="email" />
        </div>
        <div>
            <label>Message</label>
            <textarea name="messsage" rows="10"></textarea>
        </div>
        <div>
            <input type="submit" value="Send" />
        </div>
    </fieldset>
</form>

That's it. Your form ready for submissions. We assume you have styling for your form elements.

Tricking Spambots

Our service has a simple mechanism that can prevent simple spambots sending you spam. This feature works only when you use fields to verify user's entry.

All you need to do is to add a field with the 'AntiSpam' type (honeypot), then mark it as required, and publish the form.

Here is an example.

  • Let's say, we add a field with the name 'msg-subject' (choose such a name that you are not using but which should also appear to be entered), make it required and save.
  • Publish the form to make our changes active.
  • Next step is to add the input with name 'msg-subject' in the form on our website: 
    <form action="https://formsubmits.com/forms/..../submit" method="post" >
...
<input name="msg-subject" class="msg-subject" autocomplete="off" />
...
<form>
    Note that we use class 'msg-subject' which can be described in CSS as follows: 
    input.msg-subject {
    display: none;
}
  • That's it. A spambot will likely fill out the field with some value. Our system will see that the value is not empty and will simulate successful form submission.

Uploading files

To upload a file you need to do following

  • Add enctype="multipart/form-data" to your <form>
  • Add an input with 'file' type

You can set your own file size limit in the field configuration by settings 'Min. value' and 'Max. value' field properties. Please note that max allowed file size for uploading is 20 MB (20 971 520 bytes).

Also, you can set a regular expression for uploaded file extension as mentioned in the 'Form Field Configuration' section.

<form id="contact-form" enctype="multipart/form-data" action="http://api.formsubmits.com/forms/form-id-here/submit" method="POST">
    <fieldset>
        <div>
            <label>Name</label>
            <input type="text" name="name" />
        </div>
        <div>
            <label>Email</label>
            <input type="email" name="email" />
        </div>
        <div>
            <label>Resume</label>
            <input type="file" name="resume" />
        </div>
        <div>
            <input type="submit" value="Send" />
        </div>
    </fieldset>
</form>

Redirect after submission

After a form is submitted and the process went successfully the service does redirect either to your page entered in 'Redirect_URL' property of the form or to the service own page.

Additionally, with redirect the service adds following parameters to the URL:

  • requestId - an identifier of the submission. You can use it for the reference. Note that this parameter is added only upon successful submission.
  • returnUrl - URL of the page with your form.

If the submission failed then the user gets redirected to our 'Submission Error' page where he can see errors description and then come back to re-submit the form.

AJAX submission

To use our service functionality in full we recommend to submit your forms with AJAX requests and then process response to display errors right in place.

Note: Your AJAX request must have 'X-Requested-With' header with value 'XMLHttpRequest' to be processed correctly. Usually, popular libraries like jQuery do this automatically.

Here is the description of the response our system returns upon submission attempt:

  • Code - if no errors happen the value is 0. If there are errors the value will be below zero
  • Data - this is an array in which you can find an object with submission result. The property is null if there is an error. Here is a description of the result:
    • Request_ID - human readable ID of the submission. You can use it for reference purposes only;
    • Redirect_URL - URL of a page where to redirect the user;
    • Thank_You_Message - 'Thank you' message you specified in the form configuration.
  • Errors - if Code < 0 then this field contains an object with details on the validation errors
  • Message - extra message that may be present in both cases - on submission success or failure
  • Total - a number of elements in the 'Data' field.

In case of successful submission, the response object will look like:

{
    Code: 0,
    Data: [
        {
            Redirect_URL: "http://yourwebsite.com/thank-you",
            Submission_ID: "YYYYMMDDHHmm-XXXX",
            Thank_You_Message: "Thank you for the submission"
        }
    ],
    Errors: null,
    Message: "",
    Total: 0
}

In case of validation error you will find following information in the 'Errors' object.

Let's assume that there were following validation errors: Message is required but empty and Email has an invalid email address. Here is how the response would look like:

{
    Code: -10,
    Data: null,
    Errors: {
        message: {
            errors: ["Field 'Message' is required"]
        },
        email: {
            errors: ["Field 'Email' should be a valid email address"]
        }
    },
    Message: "",
    Total: 0
}

You can use the information to display errors the way you like using JavaScript.

Processing Webhooks

If you configured the form to send notifications to your URL via POST request the service sends the following structure upon successful submission:

[
    {
        ID: "11111111-1111-1111-1111-111111111111",
        Form_ID: "11111111-1111-1111-1111-111111111111",
        Request_ID: "YYYYMMDDHHmm-XXXX",
        Redirect_URL: "where the user was redirected. If empty it means our default Thank You page.",
        Form_Data: {
            submitted data
        },
        IPAddress: "IP address of the user",
        Referer: "URL of page from which the submission was done"
    }
]

Note that service sends you an array so you might get more than one submission at once. Also, the webhook notification can come sometime after actual form submission. The time can vary.

To test how it works you can use https://webhook.site service to get a URL and use it in the 'Submit to URL' form property.

Conclusion

This is everything you need to know to start using our service for form submissions. Should you have any concerns, questions or ideas, please feel free to reach out to us by using our 'Contact Us' page.

Thank you. We hope you like the service functionality.

Sign up for free or see our pricing page.