Skip to main content

Integrations

The Integrations API lets external systems (server-to-server) push leads into Superfone in real time.

Each Superfone account can configure one or more Integrations in the dashboard. Every integration has a unique webhook URL (containing a webhook_uuid). The integration's configuration controls what happens after the lead lands: which lead stage / lead group / labels are applied, which team member is assigned (round-robin across a configured pool), and whether a follow-up task is auto-created.

This API is the recommended path for inbound lead data. For server-to-server reads/writes against your CRM (lookups, updates, assignment changes), use the Customer Management Enterprise API instead.

Endpoints​

MethodPathDescription
POST/webhook/integration/:webhook_uuidPush a lead into Superfone

Base URL​

https://prod-api.superfone.co.in/superfone

A complete webhook URL looks like:

https://prod-api.superfone.co.in/superfone/webhook/integration/8f4e2a31-2b6d-4c3a-9f1e-7a0b6c2d4e5f

Authentication​

The webhook_uuid in the URL path is the credential — there is no separate API key or request signature. Get your webhook URL from the integration's settings in the Superfone dashboard.

Treat the webhook URL as a secret

Anyone who has the full URL can push leads into your account. Store it the way you'd store a credential (secret manager, not source control), and avoid embedding it in client-side code.

CORS is allowed on this endpoint, but it's intended for server-to-server use — calling it from a browser would expose the webhook URL to anyone who opens dev tools.

Synchronous processing​

Unlike a typical async webhook, this endpoint processes the lead inline and returns the outcome in the same response — there's no background worker and no separate activity feed to poll. A 200 OK means the lead was matched/created and any configured assignment, defaults, and follow-up task were applied before the response was sent. See Receive Lead Webhook for the response shape.

Because processing happens inline, a failure (invalid phone, no active subscription, lead storage full, etc.) comes back to you directly as an HTTP error — see Error Responses — rather than being deferred to a log you have to check separately.

No built-in idempotency​

There is currently no idempotency key or delivery-dedup mechanism on this endpoint. If you retry a request (e.g. after a timeout) and the original request actually succeeded, the retry is processed again as a fresh update against the same phone number — for a matched lead this is generally safe (it re-applies the same field values), but for side effects like follow-up task creation it can create a duplicate task. If your source can double-fire, de-duplicate on your side before calling the webhook.

What happens when a lead is pushed​

  1. Looks up existing leads by every phone number in the payload.
  2. Updates any matching lead. First and last name on an existing lead are preserved if the incoming first_name looks like a phone number, or if the existing lead's name field is non-numeric (we don't overwrite a real name with sparser data).
  3. Creates a new lead if no match exists. The new lead is round-robin assigned to one of the user IDs configured on the integration (when assignment is allowed by your subscription).
  4. Applies defaults from the integration's configuration: if the payload omits lead_stage_id, lead_group_id, label_ids, source, or source_type, the values from the integration setting are used.
  5. Creates a follow-up task if the integration has a task config.

Conventions​

Phone number format​

customer_phone should be a phone number in E.164 format (international, with + prefix).

Valid: +918000000001, +14155552671

Plain 10-digit national numbers are tolerated but you'll get the most reliable lead matching with E.164.

Identifying a lead​

The webhook identifies a lead by phone number. If the payload's phone matches any existing lead's phone list (primary or secondary), that lead is updated. Otherwise, a new lead is created.

Catalog references​

When you pass lead_stage_id, lead_group_id, or label_ids directly, they must be numeric IDs from your account's catalog. To discover IDs by name, use the Customer Management lookup endpoints:

If you'd rather pass names than IDs (and update an existing lead by phone), use Create or Update Lead on the Enterprise API instead.

HTTP Status Codes​

StatusMeaning
200 OKLead was matched/created and processed. Response includes the outcome — see Success Response.
400 Bad RequestEmpty body, or no (valid) phone number found in the payload.
404 Not FoundUnknown webhook_uuid, no integration configured for it, no active subscription/addon, or lead storage is full.
500 Internal Server ErrorUnexpected server error.