Custom API

If your leads come in somewhere Whispyr doesn't connect to directly — your own website form, a landing page, a spreadsheet automation, another tool — you can still send them straight into Whispyr. You create an API key, and whoever manages that system sends each new lead to a single web address. The lead lands in Whispyr within seconds and flows through your normal assignment and automation rules, exactly like a lead from Meta Ads.

This page is the reference you (or your developer) need to set that up. You don't have to be technical to create the key — the last part, sending the lead, is a short snippet you hand to whoever built the system your leads come from.

Step 1. Create your API key

In Whispyr, go to Settings → Integrations → API Access and click Create API Key. Give it a descriptive name (for example, Website contact form) so you can tell your keys apart later.

Whispyr shows you the key once, right after you create it. Copy it immediately and store it somewhere safe — a password manager is ideal. You will not be able to see it again. If you lose it, revoke that key and create a new one.

Note: treat the key like a password. Anyone who has it can create leads in your Whispyr account. Never post it publicly or commit it into website code that visitors can view. If it leaks, revoke it from the same page and issue a new one.

Step 2. Send a lead

Send each lead as a POST request to:

https://api.whispyrai.com/api/webhook/public-api

Include your API key in the Authorization header, and put the lead's details in the request body as JSON. Here is a complete example your developer can copy, paste, and adapt — replace YOUR_API_KEY with the key from Step 1:

curl -X POST https://api.whispyrai.com/api/webhook/public-api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sara Ahmed",
    "phone": "+201001234567",
    "email": "sara@example.com",
    "campaignName": "Spring Villas Landing Page",
    "projectInterest": "Palm Hills West",
    "notes": "Asked about 3-bedroom units and payment plans."
  }'

Only name and phone are required. Everything else is optional — send whatever you have.

• name — the lead's full name. Required.
• phone — the lead's phone number. Required. Include the country code (for example +20…) so it's matched correctly.
• email — the lead's email address.
• phoneSecondary — a second phone number, if you have one.
• jobTitle — the lead's job title.
• campaignName — the campaign or source this lead came from. This becomes the lead's attribution in Whispyr, so it's worth filling in.
• projectInterest — the project or product the lead asked about.
• notes — any free-text context. Anything longer than 2,000 characters is trimmed.

What you get back

When Whispyr accepts the lead, you get a 202 response like this:

{
  "success": true,
  "ingestId": "a1b2c3d4-…",
  "message": "Lead received and queued for processing"
}

202 means "received and queued" — Whispyr processes the lead a moment later, running it through duplicate checks, assignment, and your automation rules. The ingestId is that delivery's reference; you'll see the same id in the Logs tab if you ever need to trace what happened to a specific lead.

Sending the same lead twice

If your system might retry — a network hiccup, a double-submit — you can add an Idempotency-Key header with a value that's unique to that lead (for example, the submission id from your own database):

  -H "Idempotency-Key: form-submission-84213"

Whispyr remembers that key. If the same request arrives again, Whispyr returns the original result instead of creating a duplicate lead. Without this header, two identical sends create two leads.

When something goes wrong

Whispyr replies with a status code and a short reason. The common ones:

• 401 Unauthorized — the API key is missing, wrong, or has been revoked. Check the Authorization header reads Bearer YOUR_API_KEY, and confirm the key is still Active on the API Access page.
• 400 Bad Request — the request body was rejected. Either it wasn't valid JSON, a required field (name or phone) was missing, or the phone number couldn't be read. The response names the specific field so you can fix it.
• 500 Server Error — something failed on Whispyr's side. It's safe to retry (use an Idempotency-Key so a retry can't double up).

Every inbound request — successful or not — is recorded in Settings → Integrations → API Access → Logs, with its status and the lead it produced (or why it didn't). That's the first place to look when a lead you expected doesn't show up.

Note: if you manage several franchises, an API key is scoped to a single franchise (or the umbrella) when you create it. Every lead sent with that key is attributed to that franchise. Create a separate key per franchise if you need to split incoming leads.