Enable, update or disable a form on a page

POST

/form

const url = 'https://api.quantcdn.io/v1/form';
const options = {
  method: 'POST',
  headers: {
    'Quant-Customer': 'example',
    'Quant-Project': 'example',
    'Quant-Token': '<Quant-Token>',
    'Content-Type': 'application/json'
  },
  body: '{"url":"/contact-us","form_enabled":true,"form_config":{"target_url":"/contact-us","mandatory_fields":["example"],"remove_fields":["example"],"honeypot_fields":["example"],"country_is_not":["example"],"ip_is_not":["example"],"spam_threshold":1,"spam_detect_action":"discard","recaptcha_secret_key":"example","success_message":"example","error_message_mandatory":"example","error_message_generic":"example","notification_settings":{"org_timezone":"Australia/Melbourne","org_name":"example"},"notifications":{"email":{"enabled":true,"to":"example","cc":"example","from":"example","subject":"example","reply_to":"example","options":{"text_only":true,"include_results":true}},"slack":{"enabled":true,"webhook":"example"}}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.quantcdn.io/v1/form \
  --header 'Content-Type: application/json' \
  --header 'Quant-Customer: example' \
  --header 'Quant-Project: example' \
  --header 'Quant-Token: <Quant-Token>' \
  --data '{ "url": "/contact-us", "form_enabled": true, "form_config": { "target_url": "/contact-us", "mandatory_fields": [ "example" ], "remove_fields": [ "example" ], "honeypot_fields": [ "example" ], "country_is_not": [ "example" ], "ip_is_not": [ "example" ], "spam_threshold": 1, "spam_detect_action": "discard", "recaptcha_secret_key": "example", "success_message": "example", "error_message_mandatory": "example", "error_message_generic": "example", "notification_settings": { "org_timezone": "Australia/Melbourne", "org_name": "example" }, "notifications": { "email": { "enabled": true, "to": "example", "cc": "example", "from": "example", "subject": "example", "reply_to": "example", "options": { "text_only": true, "include_results": true } }, "slack": { "enabled": true, "webhook": "example" } } } }'

Quant Forms is a setting on a published page, not a separate object. When it is enabled, a POST to the page’s URL is taken as a form submission: Quant checks it, stores it, sends the notifications and answers with the page and a message in the element with id="quant-form-result". A request with Accept: application/json gets {"ok": true|false, "msg": "..."} instead.

The page must already exist and be published. Each call writes a new revision of the page. A content push (POST /) accepts the same form_enabled and form_config keys, and a later push without them keeps the published values.

There is no delete call: send form_enabled: false to stop taking submissions. The stored submissions are kept.

A multipart submission keeps the last value of a repeated field name, so give each value its own name (for example attachments, attachments_1).

Authorizations

quant_token

Parameters

Header Parameters

Quant-Customer

required

string

The customer account name

Quant-Project

required

string

The project machine name

Request Body

application/json

object

url

required

The path of the published page

string

Example

/contact-us

form_enabled

required

Whether the page takes submissions

boolean

form_config

The settings of the form. Quant checks only presence (mandatory_fields) and absence (honeypot_fields), then stores the submission and sends the notifications.

object

target_url

The path of the page, stored with the settings

string

Example

/contact-us

mandatory_fields

Field names that every submission must contain

Array<string>

remove_fields

Field names that are dropped before the submission is stored, for example a CMS’s own hidden fields

Array<string>

honeypot_fields

Field names that must be empty. A submission with a value in one of them is refused

Array<string>

country_is_not

ISO country codes whose submissions are refused

Array<string>

ip_is_not

IP addresses whose submissions are refused

Array<string>

spam_threshold

AI spam score at or above which a submission counts as spam. 0 turns the check off

integer

<= 6

spam_detect_action

What happens to spam

string

Allowed values: discard keep

recaptcha_secret_key

ReCAPTCHA v2 secret. When set, a submission must contain a valid g-recaptcha-response

string

success_message

Shown after a successful submission

string

<= 256 characters

error_message_mandatory

Shown when a mandatory field is missing

string

<= 256 characters

error_message_generic

Shown for any other refusal

string

<= 256 characters

notification_settings

object

org_timezone

string

Example

Australia/Melbourne

org_name

string

notifications

object

email

object

enabled

boolean

Recipient address

string

from

string

subject

May contain {{field}} tokens, for example New request from {{email}}

string

reply_to

May contain {{field}} tokens

string

options

object

text_only

boolean

include_results

Include the submitted fields in the email

boolean

slack

object

enabled

boolean

webhook

A Slack incoming webhook URL

string

Responses

200

The page revision with the form settings

400

The content does not exist or is not published at this path, or the body is not valid