Form submissions

Each website form in your workspace has a public address that accepts enquiries. Every enquiry becomes a contact and a deal without anyone typing it in. This page describes that address for developers who post to it from their own HTML form, a form plugin or a server. Creating forms on the screen is covered in Website forms.

Before you start

• Website forms are available when your plan includes Website forms.
• An owner or administrator creates the form: open Deals in the sidebar, then Website forms, and select Create form. Each form has a Hosted form link and a Code for your website box.
• The form's address contains its key, 32 lower-case hexadecimal characters. It is written here as FORM_KEY. The key is not a secret, because it appears in your web page. Protection comes from the limits below.

The address

POST https://rutbacrm.com/intake/FORM_KEY

The same address with GET shows the hosted form page. Add ?lang=ar, ?lang=en, ?lang=tr or ?lang=fr to choose the language of the page and of its error messages. The hosted page cannot be shown inside an iframe on another site.

The address accepts a normal form post (application/x-www-form-urlencoded or multipart/form-data) and JSON. There is no CSRF token to send and no API key.

Fields

If page carries campaign tags in its address, such as ?utm_campaign=ramadan-sale, and you did not send the tags separately, they are read from it.

A field named website is an ordinary field and no longer stops the enquiry. Code copied from Code for your website before the trap was renamed has a hidden website field: it still delivers enquiries but no longer stops spam, so copy the code again.

Field names from form plugins

You can keep the field names your form plugin already uses. These names are recognised, without regard to capital letters:

Nested plugin data is read too: fields under fields or form_fields, by their ID or their title, with raw_value or value, and the page address under meta. Up to 50 nested fields are read.

Send an enquiry from a server

curl -X POST https://rutbacrm.com/intake/FORM_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Layla Hassan", "email": "layla@example.com", "phone": "+966500000003", "message": "Do you ship to Jeddah?", "consent": "1", "page": "https://shop.example.com/contact?utm_source=google&utm_campaign=ramadan-sale"}'

Send Accept: application/json to get JSON answers. Without it, the address answers with the hosted thank-you page or the form with its errors, which is what a plain HTML form wants.

A server, or a form plugin on your website's server, sends every enquiry from one address. Enter that server's public IP address in the form's Your website server's address (optional) and click Save address, so the per-address hourly limit below does not hold it back. Only a public IPv4 or IPv6 address is accepted.

Responses

The answer is the same 200 whether the person was new or already known, so a visitor cannot use the form to find out whether an email is on file.

What happens to an enquiry

The enquiry is matched against active contacts by email or phone, and existing details are never overwritten:

The deal is named after the form and the person, and goes to the person chosen under Assign new deals to, or else to the contact's owner. The message becomes a note. The consent time, page and campaign tags are kept with the enquiry. The visitor's IP address is not stored.

Limits

Good to know

• There are no CORS headers. A browser script on another site cannot read the answer, and a JSON post from a browser is blocked before it is sent. From a web page, use a normal form post. Use JSON from servers.
• The Replace the link button gives the form a new key at once. The old address answers 404 from then on, so update your site straight away.
• File uploads are not stored, and fields other than those above are ignored.

Troubleshooting