API Reference

FormJam's API is a firehose which means it will accept any payload you can throw at it (with some restrictions).

The API will attempt to parse out the Defined Fields (see below) and will store any additional fields supplied as JSON key-values.

Endpoint

FormJam's API is located at

https://api.formjam.io/form/<uuid>

The uuid (and the full URL for your form) can be obtained in the Dashboard.

Authentication

The FormJam Public API does NOT require authentication.

Request Format

FormJam accepts HTTP POST requests formatted using

  • JSON (Content-Type: application/json) or
  • HTML Form Data (Content-Type: application/x-www-form-urlencoded).

Defined Fields

You can optionally specify the following fields, which are the most common and useful for a Contact Form. FormJam will parse them from your form submissions and treat them according to their semantic meaning.

  • message - the message text a user provides. This field will be formatted and escaped in any emails sent by FormJam.

  • subject - the subject of the message. This helps to populate the subject of emails sent by FormJam.

  • email - the email address of the user submitting the form. If specified, we validate that the email is valid. Emails sent by FormJam will automatically have their Reply-To field set to value of this field if it is specified.

  • firstName and lastName - the name fields for the user submitting the form

  • phoneNumber / contactNumber - the phone number of the user submitting the form. If specified, we validate that the phone number is a valid local or international phone number (validator used: https://github.com/validatorjs/validator.js/#isMobilePhone).

  • consentGiven - a boolean indicating if the user has consented to the form data being processed. This generally means that the user accepts the site's Privacy Policy.

    If the requireConsent option is enabled in your Form's configuration, this field will be required to submit the form. requireConsent is disabled by default to allow you to prototype forms quickly, however, we strongly recommend turning it on.

  • marketingConsentGiven - a boolean indicating if the user has consented to their data being used for marketing purposes. This is different to the consentGiven field in that, typically, a user must consent to their data being processed according to the Privacy Policy, but must be able to opt-out of marketing emails and communication.

    Whilst this can become a lot more complex, e.g. for consenting to different types of communication, FormJam handles this as a boolean. If you need more custom behaviour, you can use additional fields.

✏️
For any of the above fields, you can use UPPERCASE, lowercase, snake_case, camelCase or kebab-case - the API will accept and parse your response.

Additional Fields

Any fields which do not match our Defined Fields will be copied as provided and stored as part of your Form Submission. Any Additional Fields will be displayed in the FormJam emails sent, will be available in Zapier, and be visible in the Submissions view in the Dashboard.

Restrictions

  • Your request size must not exceed 250KB.
  • You may not use Additional Fields that start with or contain the string __formjam.
  • You cannot disable parsing of a Defined Field.
  • You will be rate-limited depending on your billing plan, but will always be spike-protected by a maximum rate limit of 500 requests per second.

If any of these restrictions are getting in your way, get in touch with us at support@formjam.io (we're really curious what you're building 😅).