Neuron Leads API
Lead generation — capture leads from CSV/text/document/web/social/tool/stream sources into a deduped pool, run/schedule sources, convert to contacts. Live ingestion via the Bot API.
Lead generation — capture leads from CSV/text/document/web/social/tool/stream sources into a deduped pool, run/schedule sources, convert to contacts. Live ingestion via the Bot API.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/neuron-ng:neuron-ng-leads-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Neuron Leads API
version: 1.0.0
description: 'API reference for Neuron — the AI-powered WhatsApp chatbot platform.
Neuron lets you build intelligent chatbots with tool integrations, knowledge bases, and human-in-the-loop monitoring.
## Authentication
Most endpoints require a JWT bearer token obtained from `POST /auth/login`.
Bot API endpoints use API keys prefixed with `nrn_`.
The **Social API** (`/social`) is organization-scoped — authenticate with an **account token** (`nrn_acc_`, from Dashboard → Settings → Account Tokens). Bot API keys are also accepted for backward compatibility but are legacy for this API.
## Response Format
All responses follow the envelope: `{ success: boolean, data?: any, error?: { message, code } }`'
servers:
- url: /api/v1
description: API v1
tags:
- name: Leads
description: Lead generation — capture leads from CSV/text/document/web/social/tool/stream sources into a deduped pool, run/schedule sources, convert to contacts. Live ingestion via the Bot API.
paths:
/leads:
get:
tags:
- Leads
summary: List leads (pool)
security:
- BearerAuth: []
parameters:
- name: status
in: query
schema:
type: string
description: Filter by status
- name: sourceId
in: query
schema:
type: string
description: Filter by source
- name: search
in: query
schema:
type: string
description: Name/phone/handle/email
- name: page
in: query
schema:
type: string
description: Page
- name: limit
in: query
schema:
type: string
description: Items per page (max 200)
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
'200':
description: Paginated list
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Lead'
total:
type: integer
page:
type: integer
limit:
type: integer
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getLeads
x-operation-id-source: derived
/leads/stats:
get:
tags:
- Leads
summary: Lead counts by status
security:
- BearerAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
new:
type: integer
enriched:
type: integer
contacted:
type: integer
converted:
type: integer
rejected:
type: integer
total:
type: integer
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getLeadsStats
x-operation-id-source: derived
/leads/extract:
post:
tags:
- Leads
summary: Ad-hoc extraction (paste/csv/document/web) — saves to the pool without a…
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
type: object
required:
- type
- config
properties:
type:
type: string
enum:
- csv
- text_paste
- document
- web_scrape
- tool_output
- instagram
- x
- facebook
- tiktok
config:
type: object
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
created:
type: integer
skipped:
type: integer
sample:
type: array
items:
type: object
note:
type: string
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postLeadsExtract
x-operation-id-source: derived
/leads/{id}:
get:
tags:
- Leads
summary: Get a lead
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Lead'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getLeadsById
x-operation-id-source: derived
patch:
tags:
- Leads
summary: Update lead status
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Lead'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: patchLeadsById
x-operation-id-source: derived
delete:
tags:
- Leads
summary: Delete a lead
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteLeadsById
x-operation-id-source: derived
/leads/{id}/convert:
post:
tags:
- Leads
summary: Promote a phone-bearing lead to a contact
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
properties:
addToList:
type: string
description: Contact list name to add the new contact to
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
converted:
type: boolean
contactId:
type: string
format: uuid
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postLeadsByIdConvert
x-operation-id-source: derived
/lead-sources:
get:
tags:
- Leads
summary: List lead sources
security:
- BearerAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/LeadSource'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getLeadSources
x-operation-id-source: derived
post:
tags:
- Leads
summary: Create a lead source
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- type
properties:
name:
type: string
type:
type: string
enum:
- csv
- text_paste
- document
- web_scrape
- tool_output
- instagram
- x
- facebook
- tiktok
- stream
config:
type: object
scheduleKind:
type: string
enum:
- cron
- interval
- once
- manual
schedule:
type: object
timezone:
type: string
enabled:
type: boolean
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/LeadSource'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postLeadSources
x-operation-id-source: derived
/lead-sources/{id}:
put:
tags:
- Leads
summary: Update a lead source
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/LeadSource'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: putLeadSourcesById
x-operation-id-source: derived
delete:
tags:
- Leads
summary: Delete a lead source
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: deleteLeadSourcesById
x-operation-id-source: derived
/lead-sources/{id}/toggle:
post:
tags:
- Leads
summary: Enable/disable a source
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/LeadSource'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postLeadSourcesByIdToggle
x-operation-id-source: derived
/lead-sources/{id}/run:
post:
tags:
- Leads
summary: Run a source now (queues extraction)
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'202':
description: Queued
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postLeadSourcesByIdRun
x-operation-id-source: derived
/lead-sources/{id}/runs:
get:
tags:
- Leads
summary: Source run history
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: page
in: query
schema:
type: string
description: Page
- name: limit
in: query
schema:
type: string
description: Items per page
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
'200':
description: Paginated list
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LeadGenRun'
total:
type: integer
page:
type: integer
limit:
type: integer
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getLeadSourcesByIdRuns
x-operation-id-source: derived
components:
schemas:
LeadSource:
type: object
properties:
id:
type: string
format: uuid
orgId:
type: string
format: uuid
name:
type: string
type:
type: string
enum:
- csv
- text_paste
- document
- web_scrape
- tool_output
- instagram
- x
- facebook
- tiktok
- stream
config:
type: object
description: 'type-specific: text_paste {text}; web_scrape {url|urls[]}; document {mediaUrl,mimeType}; tool_output {toolId,args?}; instagram/x/facebook/tiktok {channelId?, query?|hashtag?, limit?}; csv {rows[]}; stream {triggerTaskId?}'
scheduleKind:
type: string
enum:
- cron
- interval
- once
- manual
schedule:
type: object
timezone:
type: string
enabled:
type: boolean
lastRunAt:
type:
- string
- 'null'
format: date-time
nextRunAt:
type:
- string
- 'null'
format: date-time
runCount:
type: integer
leadCount:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
LeadGenRun:
type: object
properties:
id:
type: string
format: uuid
sourceId:
type:
- string
- 'null'
format: uuid
orgId:
type: string
format: uuid
status:
type: string
enum:
- running
- completed
- failed
trigger:
type: string
enum:
- manual
- schedule
- task
- stream
createdCount:
type: integer
skippedCount:
type: integer
summary:
type:
- string
- 'null'
error:
type:
- string
- 'null'
startedAt:
type: string
format: date-time
finishedAt:
type:
- string
- 'null'
format: date-time
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
message:
type: string
code:
type: string
Lead:
type: object
properties:
id:
type: string
format: uuid
orgId:
type: string
format: uuid
sourceId:
type:
- string
- 'null'
format: uuid
name:
type:
- string
- 'null'
phone:
type:
- string
- 'null'
email:
type:
- string
- 'null'
handle:
type:
- string
- 'null'
platform:
type:
- string
- 'null'
company:
type:
- string
- 'null'
title:
type:
- string
- 'null'
bio:
type:
- string
- 'null'
sourceUrl:
type:
- string
- 'null'
status:
type: string
enum:
- new
- enriched
- contacted
- converted
- rejected
score:
type: integer
tags:
type: array
items:
type: string
metadata:
type: object
notes:
type:
- string
- 'null'
contactId:
type:
- string
- 'null'
format: uuid
description: Set once the lead is promoted to a contact.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token from POST /auth/login
ApiKeyAuth:
type: http
scheme: bearer
description: Bot API key (nrn_xxx) from bot API keys management
AccountTokenAuth:
type: http
scheme: bearer
description: Account token (nrn_acc_xxx) from Dashboard > Settings > Account Tokens