Docs

Form API

Send leads to Amerta AI from your own form or server: the address, the fields to send, how to find the form key and calculate the check field, and the reply.

Overview

Every form can be sent without the form page: post its fields to the form's address and the lead arrives in Amerta AI like any other, with its ad source, notifications and integrations.

POST https://amerta.ai/form/{domain}/{form-id}/{locale}/

Use it to send leads from your own form, your website's backend, a landing page builder or another system.

A submission is the form's fields plus two values that protect it from spam: the form key and an empty check field. The sections below show how to find each one.

What to send

Send the values as application/x-www-form-urlencoded, or multipart/form-data when the form has a file field.

Name Value Required
key The form's key (see The form key) Yes
field_N (check field) Empty. Its number is calculated (see The check field) Yes, empty
field_1, field_2… The answers, one per field (see Field names) The required fields
utm_source, utm_medium, utm_campaign, utm_term, utm_content The ad source No
clid The Google click ID, as gclid-…, gbraid-… or wbraid-… No
fbclid The Meta click ID No
referer The page the lead was sent from, such as https://www.example.com/contact/ No
_branch A branch's slug, when you use branches No
_ip The visitor's IP address, when you send from your server (see Sending from your server) No
_validate 1 to check the answers without saving the lead No

Add Accept: application/json to the request, or ?json to the address, to get a JSON reply. Without it you get the form's HTML page.

Field names

Each field is named field_ plus its number, such as field_1.

To see the numbers, open Forms → Forms and click Fields next to the form; the Name column shows them. Or open the form's address in a browser and look at the name of each field in the page source.

Numbers are counted per language, so check the language you send to: /en/ and /ar/ can have different numbers for the same question.

How to fill each kind of field:

Field Send
Text, Paragraph, Hidden, Number, Range The text or number
Email A valid email address
Phone (with Country Code) The number in international format, such as +971501234567. Without the +, the field's Default Country Code is used
Date YYYY-MM-DD, such as 2026-11-20
Select Box, Options The choice's value (not its label)
Select Box with Multiple The name with [] once per choice: field_5[]=botox&field_5[]=fillers
Checkbox The checkbox's Value, or leave it out for unticked
File The file, with multipart/form-data

Buttons, titles and Custom HTML have nothing to send.

The form key

Every form has a fixed key. Open the form's address in a browser and look for the hidden field named key in the page source:

<input type="hidden" id="key" name="key" value="zc8snq40dqsscc0800oso0sw8g8cko" />

Send that value as key. It doesn't change when you edit the form, so you only need to copy it once. A wrong key is refused with "Form key is invalid."

The check field

Every form has a hidden field that people never see and bots fill in. It must be sent, and it must be empty; a submission without it, or with a value in it, is refused as spam.

Its name is field_ plus a number you can calculate from the form's fields in that language:

number of fields + the sum of their numbers

Count every field in the editor for that language, including titles, Custom HTML and buttons.

Example: a form with Name field_1, Email field_2, Phone field_3 and Message field_4:

4 fields + (1 + 2 + 3 + 4) = 4 + 10 = 14   →   field_14

So that form is sent with field_14= (empty).

The number changes when you add or remove a field, so recalculate it after editing the form, or read it from the page source: it's the textarea after the key field, inside a hidden block.

Example

The form above, with curl:

curl -X POST "https://amerta.ai/form/{domain}/2/en/" \
  -H "Accept: application/json" \
  --data-urlencode "key=zc8snq40dqsscc0800oso0sw8g8cko" \
  --data-urlencode "field_14=" \
  --data-urlencode "field_1=Sara Ahmed" \
  --data-urlencode "field_2=sara@example.com" \
  --data-urlencode "field_3=+971501234567" \
  --data-urlencode "field_4=I'd like to book a consultation" \
  --data-urlencode "utm_source=google" \
  --data-urlencode "utm_campaign=spring" \
  --data-urlencode "referer=https://www.example.com/contact/"

In PHP:

$ch = curl_init('https://amerta.ai/form/{domain}/2/en/');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
    CURLOPT_POSTFIELDS => http_build_query([
        'key'      => 'zc8snq40dqsscc0800oso0sw8g8cko',
        'field_14' => '',
        'field_1'  => $_POST['name'],
        'field_2'  => $_POST['email'],
        'field_3'  => $_POST['phone'],
        'field_4'  => $_POST['message'],
        'utm_source' => $_COOKIE['utm_source'] ?? '',
        'referer'  => $_SERVER['HTTP_REFERER'] ?? '',
        '_ip'      => $_SERVER['REMOTE_ADDR'],
    ]),
]);
$result = json_decode(curl_exec($ch), true);

In Node.js:

const res = await fetch('https://amerta.ai/form/{domain}/2/en/', {
  method: 'POST',
  headers: { Accept: 'application/json' },
  body: new URLSearchParams({
    key: 'zc8snq40dqsscc0800oso0sw8g8cko',
    field_14: '',
    field_1: 'Sara Ahmed',
    field_2: 'sara@example.com',
    field_3: '+971501234567',
    field_4: "I'd like to book a consultation",
    _ip: visitorIp,
  }),
});
const result = await res.json();

The reply

When the lead is saved:

{
  "status": "success",
  "submission_id": "…",
  "form_id": 2,
  "message": "Thank you for your inquiry, One of our team members will be back to you as soon as possible"
}

message is the form's thank-you text. When the form redirects to a thank-you page instead, the reply has redirect with that address.

When something is wrong, status is error and error lists each problem; a field's problem has its name:

{
  "form_id": 2,
  "status": "error",
  "message": "Please fix the field errors and try again.",
  "error": [
    { "type": "field", "name": "field_2", "message": "Please enter a valid email address in \"Email\" field." }
  ]
}
Error Why
Form key is invalid. key is missing or wrong
Invalid form submission: field_N The check field is missing or not empty; recalculate its number
Please enter a valid … / … is required A field's answer is missing or in the wrong format
You have already submitted this form… The same answers were sent within the last minute
You have just submitted your form… Two sends from the same visitor a few seconds apart
You have submitted this form too many times… More than 150 sends from one IP address in an hour
Form doesn't exist or not active Wrong domain or form number, or the form isn't enabled

Test without saving

Add _validate=1 to check everything (the key, the check field and every answer) without saving a lead or sending notifications:

{ "status": "success", "message": "Validation successful, You can now resubmit the form to save the data" }

Remove it to send for real. To test the whole path, send one real lead and delete it afterwards from Leads.

Sending from your server

Send from your server, not from the visitor's browser: the form's address doesn't allow other websites to read its reply, so a browser fetch from your site can't see whether it worked.

When you send from your server:

  • Send _ip with the visitor's IP address. The spam limits count sends per IP address; without it, every lead comes from your server's address and they quickly hit the limits.
  • Send referer with the page the visitor was on, since your server has no page of its own. It's what Amerta AI shows as the site the lead came from.
  • Send the ad source. Read utm_*, gclid and fbclid from the visitor's landing page address or your own cookies and pass them on. The embed script keeps them for you in cookies for 60 days.

A form with the Cloudflare Turnstile (Captcha) field can't be sent this way, since it needs the visitor to pass the captcha in the browser. Use a form without it for the API.