Leads
A lead is an enquiry, always attached to a contact. See the Leads guide for the concepts.
Base URL https://api.leadx.in/api/key/protected. Every request needs an apikey header — see Authentication.
13 endpoints.
GET /lead
List leads for the company, with the standard pagination, search and filter contract.
Auth apikey
:::note Used by the web app
components/CustomField.jsx, components/GenerateEmailTemplateModal.jsx, components/GenerateWhatsappTemplateModal.jsx and 4 more
:::
Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.
POST /lead
Create a lead, creating or reusing the contact behind it.
Auth apikey · Success 201
:::note Used by the web app
components/CustomField.jsx, components/GenerateEmailTemplateModal.jsx, components/GenerateWhatsappTemplateModal.jsx and 4 more
:::
Request body
| Field | Default | Notes |
|---|---|---|
contactId | — | Attach to an existing contact and skip contact matching. |
formData | {} | System and custom fields together — see Custom fields. |
email | — | Contact email. The default deduplication key. |
contactNumber | {} | { countryCode, number }. |
name | "" | Contact name. |
work_phone_number | "" | { countryCode, number }. |
whatsapp_contact_number | "" | { countryCode, number }. |
source | — | Dropped silently if it is not a known source value. |
contactData | {} | Extra fields for the contact being created. |
skipInvalid | — | Keep going past rows that fail validation instead of rejecting the request. |
Response — data is one Lead object.
Errors ContactNotFound_400 · InvalidCustomFieldValue_400 · InvalidCustomField_400 · InvalidSystemField_400 · UniqueKeyInvalid_400
PUT /lead
Apply one set of changes to many leads.
Auth apikey · Success 200
:::note Used by the web app
components/CustomField.jsx, components/GenerateEmailTemplateModal.jsx, components/GenerateWhatsappTemplateModal.jsx and 4 more
:::
Request body — the standard bulk selection (ids, nids, selectAll) plus formData and updateType.
DELETE /lead
Soft-delete leads (isDeleted: true).
Auth apikey · Success 200
:::note Used by the web app
components/CustomField.jsx, components/GenerateEmailTemplateModal.jsx, components/GenerateWhatsappTemplateModal.jsx and 4 more
:::
Request body — the standard bulk selection: ids, nids, selectAll. Query-string filters apply when selectAll is set.
Response — data is one Lead object. (Resource deduced from the collections this handler reads, not read off an explicit return.)
GET /lead/:id
Fetch one lead by id.
Auth apikey
:::note Used by the web app
components/AILeadGenerationWidget.jsx, components/AILeadGenieWidget.jsx, pages/AILeadGeneration.jsx and 2 more
:::
Path parameters
| Name | |
|---|---|
id | Required |
Query parameters
| Field | Default |
|---|---|
populate | — |
Response — data is one Lead object.
Errors LeadNotFound_404
PUT /lead/:id
Update lead.
Auth apikey · Success 200 · Emits lead.updated
:::note Used by the web app
components/AILeadGenerationWidget.jsx, components/AILeadGenieWidget.jsx, pages/AILeadGeneration.jsx and 2 more
:::
Path parameters
| Name | |
|---|---|
id | Required |
Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.
Request body
| Field | Default | Notes |
|---|---|---|
formData | {} | System and custom fields together — see Custom fields. |
tags | — | Tag ids. |
category | — | Contact category id. |
Response — data is one Lead object. (Resource deduced from the collections this handler reads, not read off an explicit return.)
Errors InvalidCustomFieldValue_400 · InvalidCustomField_400 · InvalidSystemField_400 · LeadNotFound_400
POST /lead/bulk
Create up to 500 leads in one request, with per-item success and failure.
Auth apikey
Request body
| Field | Default | Notes |
|---|---|---|
formData | — | System and custom fields together — see Custom fields. |
contactId | — | |
contactNumber | — | |
work_phone_number | — | |
whatsapp_contact_number | — | |
email | — | |
name | — | |
skipInvalid | — | Keep going past rows that fail validation instead of rejecting the request. |
Errors ContactNotFound_400 · InvalidCustomFieldValue_400 · InvalidCustomField_400 · InvalidSystemField_400 · UniqueKeyInvalid_400
GET /lead/import
List imports.
Auth apikey
Query parameters — the standard list contract: p, n, sortBy, sortOrder, searchBy, searchValue, filters, advancedFilters, ids, nids. See Pagination and Filtering.
POST /lead/import
Create an import from an already-uploaded file.
Auth apikey
Prerequisites
- An uploaded file. Register it first and use the returned id as
file.POST /upload
Request body
| Field | Default | Notes |
|---|---|---|
file | — | File id from POST /upload. |
headers | — | The file's header row. Empty → EmptyFile_400. |
totalCount | — | Optional, but must be real if sent. Omitted, rows are counted at run time. |
columnMapping | {} | Header name → target field. Values may be system field paths or custom field ids. |
options | {} | Import behaviour, e.g. skipInvalid. |
tags | [] | Tag ids. |
category | — | Contact category id. |
pauseImport | true | Defaults to true — created paused so the mapping can be reviewed. |
userEnquiry | — |
Required: importType, fileId — nested inside another field (commonly formData), or checked under a different internal name, so they do not appear as top-level body fields above.
Response — data is one File object. (Resource deduced from the collections this handler reads, not read off an explicit return.)
Errors EmptyFile_400 · FileNotFound_400 · NoRowsInFile_400
DELETE /lead/import
Delete imports.
Auth apikey · Success 200
Request body — the standard bulk selection: ids, nids, selectAll. Query-string filters apply when selectAll is set.
Response — data is null; the outcome is the status code and message.
GET /lead/import/:id
Fetch one import, including progress and row errors.
Auth apikey
:::note Used by the web app
pages/ImportLeads.jsx
:::
Path parameters
| Name | |
|---|---|
id | Required |
Errors ImportNotFound_400
PUT /lead/import/:id
Update an import — this is also how a paused import is resumed.
Auth apikey
:::note Used by the web app
pages/ImportLeads.jsx
:::
Path parameters
| Name | |
|---|---|
id | Required |
Request body
| Field | Default | Notes |
|---|---|---|
columnMapping | — | |
options | — | |
tags | — | Tag ids. |
category | — | Contact category id. |
userEnquiry | — |
Required: id — nested inside another field (commonly formData), or checked under a different internal name, so they do not appear as top-level body fields above.
Errors ImportAlreadyPaused_400 · ImportAlreadyRunning_400 · ImportNotFound_400 · InvalidImportStatus_400 · NoRowsInFile_400 · RowFromGreaterThanRowTo_400 · RowFromOutOfRange_400
POST /lead/lead-gen-ai
Start an AI lead-generation run.
Auth apikey · Success 201
Request body
| Field | Default | Notes |
|---|---|---|
prompt | — | The outreach goal, in plain language. |
requestedCount | 25 | |
industry | "" | |
additionalFilters | {} | |
type | contact | |
aiType | gemini | AI provider. Defaults to Gemini. |
enrich | false | |
userEnquiryEnabled | true |