How to Create & Integrate a Form

1. Concepts

A form is active by default. Only active forms accept submissions.

2. Creating a Form

Your fields are stored as JSON, for example:

[
  { "name": "name",    "label": "Full Name",     "type": "text",     "required": true  },
  { "name": "email",   "label": "Email Address", "type": "email",    "required": true  },
  { "name": "message", "label": "Message",       "type": "textarea", "required": true  }
]

3. Supported Field Types

4. Managing a Form

Open Forms → Edit to manage an existing form:

• Active toggle — pause a form; an inactive form rejects submissions with 401.
• Notification email — where new-lead alerts are sent (defaults to your account email).
• Thank-You email — auto-reply to the submitter: enable it, pick which field holds their address, set a subject, and build the HTML template (with image upload and a test send) in Forms → Template.
• Regenerate API key — issues a new key; the old one stops working immediately, so update your integrations.

5. Integrating a Form

Open Forms → Integration to find your credentials and copy-paste snippets.

Credentials

You need two values: your Form UUID (goes in the URL) and your API key (goes in the X-API-Key header).

The endpoint

GET|POST  {APP_BASEURL}/api/v1/lead/{form_uuid}

# example
https://databeam.interfacebeam.com/api/v1/lead/3f9c1e7a-...-d2

Authentication

Send the API key on every request. The key must belong to an active form, and the UUID in the URL must match the form that owns the key.

X-API-Key: {api_key}

Sending data

The payload can be sent three ways — keys should match your field names:

6. Code Recipes

Plain HTML form

<form action="https://databeam.interfacebeam.com/api/v1/lead/{form_uuid}" method="POST">
  <input name="name" type="text" required>
  <input name="email" type="email" required>
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

JavaScript (fetch)

fetch('https://databeam.interfacebeam.com/api/v1/lead/{form_uuid}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': '{api_key}',
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@acme.com',
    message: 'Hello!',
  }),
})
  .then((r) => r.json())
  .then((data) => console.log('Captured', data.lead_id));

PHP (cURL)

$data = ['name' => 'John Doe', 'email' => 'john@acme.com', 'message' => 'Hello!'];

$ch = curl_init('https://databeam.interfacebeam.com/api/v1/lead/{form_uuid}');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'X-API-Key: {api_key}'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Command line (cURL)

curl -X POST \
  'https://databeam.interfacebeam.com/api/v1/lead/{form_uuid}' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: {api_key}' \
  -d '{"name":"John Doe","email":"john@acme.com","message":"Hello!"}'

7. Responses & Status Codes

Success (200 OK):

{
  "status": "success",
  "message": "Lead received successfully.",
  "lead_id": 1234
}

Errors return { "status": "error", "message": "..." }:

8. Rate Limiting

Submissions are limited to 5 requests per 60 seconds per API key. On the 6th request in the window you get 429 with these headers:

Retry-After: <seconds>
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0

Successful responses also include X-RateLimit-Limit and X-RateLimit-Remaining.

9. Viewing & Exporting Leads

• Leads — every captured lead. Open one to see the full payload, IP, user agent, and referrer.
• Export — download your leads as CSV for your CRM or spreadsheet.

10. Troubleshooting

Need to capture leads from this very site? Use the Contact Us button in the corner — it's powered by a DataBeam form. Ready to build your own? Start free →