Connect your own form

Auto-trigger a phone call when your existing lead form is submitted.

You already have a lead form. You do not have to replace it — have it trigger a phone call as well, so a submitted form rings your team within seconds instead of sitting in an inbox.

This is the highest-value integration the widget has. Speed of response is the single biggest driver of inbound lead conversion, and a form that rings you immediately beats one that emails you every time.

Two ways

Approach	Use when
Ask the widget	The widget is installed. Shortest path, and it handles validation for you.
Hand off to the widget	You want the widget's own confirmation screen and ringing state.
Post directly	You want your own interface end to end, or you are submitting from a server.

Ask the widget

If the widget is already on the page, requestCallback() does the whole thing and tells you what happened:

<form id="enquiry">
  <input name="name" placeholder="Your name" required>
  <input name="phone" type="tel" placeholder="Phone number" required>
  <button type="submit">Request a callback</button>
</form>
<p id="enquiry-status" role="status"></p>

<script>
document.getElementById("enquiry").addEventListener("submit", async function (e) {
  e.preventDefault();
  var status = document.getElementById("enquiry-status");
  status.textContent = "Requesting your call…";

  var result = await window.LimeCall.requestCallback(e.target.phone.value, {
    name: e.target.name.value
  });

  status.textContent = result.ok
    ? "We're calling you now — please keep your phone nearby."
    : result.message;
});
</script>

No key in your code, no endpoint to get right, and the phone number is validated before anything leaves the browser. It resolves { ok, id, message } and never rejects, so there is nothing to catch.

Hand off to the widget

To show the widget's own confirmation and ringing state instead of your own, pass the number to call() and let it take over:

document.getElementById("enquiry").addEventListener("submit", function (e) {
  e.preventDefault();
  if (window.LimeCall) window.LimeCall.call(e.target.phone.value);
});

call() returns a boolean that tells you nothing about the outcome — listen for callback:requested and callback:failed, or use requestCallback() above.

Pair either with hideLauncher() if you do not want the floating button on the page.

Post directly

To keep your own interface entirely, post to the widget's public endpoint. This uses your widget key — the publishable one from your snippet's data-key — not a secret API key.

async function requestCallback(fields) {
  const res = await fetch("https://dashboard.limephone.io/api/public/callback", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Widget-Key": "YOUR_WIDGET_KEY"
    },
    body: JSON.stringify(fields)
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.message || "Callback request failed");
  return body;            // { id: "..." }
}

Use the same host as your snippet's data-api value.

Fields

Field	Required	Notes
phone	yes	The number to call back, international format.
name	no	Shown to whoever takes the call.
email	no	Stored on the resulting lead.
department	no	Routes to a specific team.
captured	no	Extra fields you collected, carried onto the lead.
sessionId	no	Ties the request to a widget session for attribution. If the widget is on the page, get it from window.LimeCall.getVisitorId().

Success returns the callback's id. A failure returns a message worth showing the visitor — it is where "outside business hours" arrives.

Scheduling instead

Same shape plus a time, to a different path:

fetch("https://dashboard.limephone.io/api/public/callback/schedule", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Widget-Key": "YOUR_WIDGET_KEY" },
  body: JSON.stringify({ phone: "[phone]", scheduledAt: "2026-09-15T09:30:00Z" })
});

Worked example — an existing lead form

A complete drop-in: keep your form and its styling, add a call request, and fall back gracefully when nobody can be reached.

<form id="lead-form">
  <input name="name"    placeholder="Name" required>
  <input name="email"   placeholder="Email" type="email" required>
  <input name="phone"   placeholder="Phone" type="tel" required>
  <textarea name="message" placeholder="How can we help?"></textarea>
  <button type="submit" id="lead-submit">Send &amp; get a call back</button>
</form>
<p id="lead-status" role="status"></p>

<script>
(function () {
  var form   = document.getElementById("lead-form");
  var button = document.getElementById("lead-submit");
  var status = document.getElementById("lead-status");

  form.addEventListener("submit", async function (e) {
    e.preventDefault();
    button.disabled = true;                         // never double-submit
    status.textContent = "Requesting your call…";

    var data = Object.fromEntries(new FormData(form));

    // 1. Your own backend still gets the lead, exactly as before.
    try {
      await fetch("/api/leads", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data)
      });
    } catch (err) {
      // Don't abandon the call request just because your own endpoint failed.
      console.error("Lead save failed", err);
    }

    // 2. Then ask LimeCall to ring both sides.
    try {
      const res = await fetch("https://dashboard.limephone.io/api/public/callback", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Widget-Key": "YOUR_WIDGET_KEY"
        },
        body: JSON.stringify({
          phone: data.phone,
          name:  data.name,
          email: data.email,
          captured: { message: data.message }       // carried onto the lead
        })
      });
      const body = await res.json();

      if (res.ok) {
        status.textContent = "Thanks — we're calling you now. Please keep your phone nearby.";
      } else {
        // Closed, blocked, or an unsupported country. Say what the API said.
        status.textContent = body.message || "We've got your details and will be in touch.";
        button.disabled = false;
      }
    } catch (err) {
      status.textContent = "We've got your details and will be in touch.";
      button.disabled = false;
    }
  });
})();
</script>

What that example gets right

Your backend still receives the lead. The call request is added alongside, not instead. If LimeCall is unreachable you have still captured the enquiry.

It tells the visitor a call is coming. Someone who does not expect a call does not answer an unknown number, and the whole point is lost. Say it before the phone rings.

It shows the API's own message on failure. "We're closed right now" is useful; "Something went wrong" is not.

It disables the button. A visitor who clicks twice otherwise gets rung twice.

captured carries the free-text field onto the lead, so whoever picks up can see what was asked before they speak.

Only promise a call someone can take

Ask before you offer. hasAvailableAgents() accounts for working hours, whether the people the widget routes to still resolve, and — on an AI-routed widget — whether you have minutes left:

if (await window.LimeCall.hasAvailableAgents()) {
  button.textContent = "Send & get a call back";
} else {
  button.textContent = "Send";     // same form, no promise of a call
}

Changing the label is better than hiding the option. The lead is still captured either way; the visitor just is not told to expect a ringing phone that never comes.

If you are posting directly rather than using the widget, the request still succeeds outside hours — the response message is where "we're closed right now" arrives, which is why the example above shows it to the visitor verbatim.

Which key is which

The widget key (data-key) is publishable — it is already in your page source and belongs in browser code. A secret key (sk_live_…) is not: putting one in front-end code exposes your whole account to anyone who opens developer tools. The widget endpoints take X-Widget-Key; the REST API takes Authorization: Bearer. They are not interchangeable.

See API keys.

Doing it server-side instead

If your form already posts to your own backend, create the callback there. It is the right choice when you want to validate, deduplicate, enrich or rate-limit before spending a call — and the visitor's browser never has to be trusted.

It is the same endpoint, with a secret key instead of a widget key:

	Browser	Your server
Header	X-Widget-Key: pk_live_…	Authorization: Bearer sk_live_…
Origin	Must be on your allowed list	Not checked
fromNumber	From your saved widget settings	Required in the body
Daily cap	Your widget's cap (default 50)	dailyCallbackCap, default 200

The secret key needs the calls:write scope. Without it the request is rejected with 403 insufficient_scope — placing a call spends real money, so it is held to the same scope requirement as every /api/v1 route.

Node

// Node 18+. Never expose sk_live_ to a browser.
export async function requestCallback({ phone, name, email }) {
  const res = await fetch("https://dashboard.limephone.io/api/public/callback", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.LIMECALL_SECRET_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      phone,                                  // E.164, e.g. [phone]
      fromNumber: process.env.LIMECALL_FROM,  // required, and must be a number you own
      name,
      email
    })
  });

  const body = await res.json();
  if (!res.ok) {
    // body.error is a stable code; body.message is safe to show a visitor.
    throw new Error(`${body.error}: ${body.message}`);
  }
  return body.id;                             // the callback id
}

PHP

<?php
function limecall_request_callback(string $phone, ?string $name = null): string {
    $payload = array_filter([
        "phone"      => $phone,                      // E.164
        "fromNumber" => getenv("LIMECALL_FROM"),     // required
        "name"       => $name,
    ]);

    $ch = curl_init("https://dashboard.limephone.io/api/public/callback");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer " . getenv("LIMECALL_SECRET_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode($payload),
    ]);

    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $body = json_decode($raw, true);
    if ($status >= 400) {
        throw new RuntimeException("{$body['error']}: {$body['message']}");
    }
    return $body["id"];
}

What you can send

phone and fromNumber are required. name, email, department, captured and sessionId behave exactly as they do from the browser.

The server path also accepts routing overrides the browser cannot set, so one key can serve several brands or campaigns: dailyCallbackCap, bridgeProvider ("vapi" or "grok"), voiceAgentId, callableCountries, blockedCountries and blockVoip.

Errors worth handling

Status	error	Means
400	missing_from_number	fromNumber was not sent.
401	unauthorized	Key missing, malformed or revoked.
403	insufficient_scope	The key lacks calls:write.
403	from_not_owned	That caller ID is not a number on your account.
403	(destination)	The number is in a range we refuse to dial.
429	spend_cap	The daily cap is spent.

from_not_owned exists because fromNumber comes from your request body on this path. The check stops a leaked key being used to spoof someone else's caller ID.

See API keys for creating a key with the right scope.