Leadferno API: overview & core concepts

The Leadferno API documentation is publicly available in swagger.

Leadferno API is only available to our integrating partners and customers. If you're interesting in developing an application with Leadferno, please text us.

If you need to integrate, but don't have the resources to develop an integration directly, please refer to our Zapier connector.

What you can build

Receive events — new messages, new leads, new contacts, tag changes, status changes — as webhooks.
Read threads, messages, and contacts.
Send SMS and Facebook messages into an existing conversation.

Terminology

The API's names don't all match the app's names. These are the ones that catch people:

API term	What it is in the app
`customer`	Your Leadferno account — the top-level entity that owns profiles, users, tags, and billing.
`profile`	A location / inbox — the thing a phone number is attached to. An account can have several.
`prospect`	A contact. Same record, different name.
`cellphone` on a `prospect`	The contact's mobile number.
`user`	A team member with an account in the Leadferno app.
`cellphone on a user`	The number used for SMS notifications for a new lead
`thread`	A conversation with one contact on one profile.
`message.direction`	`ingress` = from the contact (inbound); `egress` = to the contact (outbound).
`message.type`	The channel: `sms`, `fb` (Facebook), `leadform_fields`, `call_request`, plus internal note types.
`cellphones[]` on a `profile`	Your profile's own Leadferno number(s) — not a contact's.
`/v0/zapier/*`	The generic webhook subscription endpoints. Not Zapier-specific — the name is historical.

Object hierarchy

MarkdownCustomer  (your Leadferno account)
└── Profile  (a location / inbox / phone number)
    └── Thread  (a conversation)
        ├── Prospect  (the contact — name, cellphone, email)
        └── Messages[]  (each has a direction and a type)

Most endpoints are scoped through this hierarchy, for example: GET /v0/profiles/{profile_uuid}/threads/{thread_uuid}.

The identifiers you need

All IDs are v4 UUIDs — 36 characters, lowercase hex with hyphens. The API rejects anything that isn't a well-formed v4 UUID with a 422.

Identifier	Scopes	Where to get it
Customer UUID	Account	`GET /v0/me` → `customer`
Profile UUID	Single phone number (Inbox) or location	`GET /v0/me` → `profiles[].profile`, or `GET /v0/customers/{customer_uuid}/profiles`
`client_id`	Your OAuth application	Issued by Leadferno, or created via the API (see Register your integration)

There is no GET /v0/profiles list endpoint. After authenticating, call:

ShellGET /v0/me
Authorization: Bearer &lt;access_token&gt;

JSON{
  "uuid": "&lt;user-uuid&gt;",
  "customer": "&lt;customer-uuid&gt;",
  "profiles": [
    { "profile": "&lt;profile-uuid&gt;", "name": "Downtown Office", "customer": "&lt;customer-uuid&gt;" }
  ]
}

or, for fuller records, GET /v0/customers/{customer_uuid}/profiles (an array of { uuid, name, default, customer, label, language, read } — note the profile UUID is profile in /me and uuid here).

If a UUID someone gave you doesn't parse as a 36-character v4 UUID, it's a transcription error. Don't guess at it — ask us to reconfirm.

Scopes

A token carries the scope of the Leadferno user who authorized it. There are three, and they nest: staff → admin → super (super is Leadferno-internal only).

staff covers reading threads/messages/contacts, sending messages, and subscribing to webhooks.
admin is additionally required to create profiles or edit auto-replies, lead forms, keywords, and AI settings.

If your integration configures profiles, have an admin complete the sign-in.