Lead sources

List lead sources

crm.lead_sources.list

Lists the org's lead sources (Meta, Google, TikTok, LinkedIn, WhatsApp, generic webhooks, forms, bookings, DMs, manual, the API source), newest first, with their destination, routing defaults, field mapping, AI scoring, health, stats and the account or line each one is bound to; filters by type and active_only; paginated by cursor (limit up to 200, default 50). The webhook URL comes only for generic sources. The secret never comes in the list: crm.lead_sources.get brings it, only for who can manage sources and never through the MCP. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records or fields are left out of the response (the permissions guide lists what each platform allows).

Scope

crm:read

Permission

View the module

MCP tool

crm_lead_sources_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.list".

Declared cost: up to 1001 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/lead-sources" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/crm/lead-sources" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one lead source

crm.lead_sources.get

Returns a lead source with its destination (prospect or deal), default pipeline, stage and labels, currency, field mapping, dedup strategy, AI scoring, health, stats and the account or line it is bound to. The webhook URL comes only for a generic source; the secret only for who can manage sources and never through the MCP. Not found for deleted sources. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Scope

crm:read

Permission

View the module

MCP tool

crm_lead_sources_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.get".

Declared cost: up to 2 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a generic or manual lead source

crm.lead_sources.create

Creates a lead source of type generic (an inbound webhook: Make, Zapier, ManyChat, a site form or any system POSTs JSON to its webhook_url, signed with its secret) or manual (a bucket for leads loaded by hand or with crm.leads.ingest and its source_id). Sets where leads go (prospect inbox or a pipeline deal), the field mapping from each incoming JSON field to a CRM field (person.email, person.phone, person.firstName, person.lastName, company.website, deal.title, deal.value, cf:<custom field slug>, custom:<key>), the default pipeline, stage, labels and currency, the dedup strategy and AI scoring. A generic source must map at least one field to person.email or person.phone. The pipeline, stage, labels and mapped fields must exist (a deal source needs its pipeline; without a stage, its first one). AI scoring of each lead consumes AI credits and stays off unless ai_qualification.enabled is sent true. Sources on a WhatsApp line, on Social Inbox accounts (DMs) or on a booking page are created with crm.lead_sources.create_whatsapp, create_social_dm and create_booking; the source of an MB Suite web form with web_forms.forms.link_crm and create_source (it creates it and links the form); Meta, Google, TikTok and LinkedIn sources by their own integration in the app. Returns the webhook URL and the secret of a generic source (the secret only outside the MCP: through the MCP it comes back empty and the person reads or regenerates it in the app, CRM → Settings → Lead sources); a manual source has neither. Requires manage_sources.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_createOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.create".

Declared cost: up to 0 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "destination": "deal",
  "type": "generic"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "destination": "deal",
  "type": "generic"
}'

Update a lead source

crm.lead_sources.update

Updates a lead source's name, active flag, destination (prospect or deal), field mapping, default pipeline and stage, default labels, currency, dedup strategy (merge, create_activity, notify, skip) or AI scoring flag, inside updates; what is not sent is kept. The routing that results is validated like at creation (pipeline, stage of that pipeline, labels of the destination, mapped fields). The system sources (Manual, API) only accept the routing defaults and AI scoring. A generic source must keep a field mapped to person.email or person.phone. It does not change which page, ad account, forms or booking a source is bound to: that is done from its integration in the app; a DM source is edited whole with crm.lead_sources.update_social_dm. Requires manage_sources. With Google Ads or LinkedIn, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.update".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a lead source

crm.lead_sources.delete

Deletes a lead source: it stops receiving leads at once, and the prospects, deals and conversations that came through it keep naming it. If it is the last source bound to a Meta page (in any organization) or to a TikTok advertiser, that page or advertiser is also unsubscribed from the platform's lead webhook. Deleting a WhatsApp source frees its line for a new source; the line itself keeps working (Messages, the Setter and the other modules that use it). The source goes to the 30-day trash. The system sources (Manual, API) cannot be deleted. Requires manage_sources. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

crm:write and “Allow deletions” (crm:delete in OAuth)

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_deleteOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.delete".

Declared cost: up to 60 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Pause a lead source

crm.lead_sources.pause

Pauses a lead source: new leads stop entering (platform webhooks keep arriving and are discarded; the connection is not touched, so reactivating needs no reconnection). Pausing a source the system paused because its integration was disconnected turns it into a manual pause. The system sources (Manual, API) cannot be paused. Idempotent. Requires manage_sources.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_pauseOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.pause".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/pause" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/pause" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Reactivate a paused lead source

crm.lead_sources.reactivate

Reactivates a paused lead source so new leads enter again. If the system had paused it because its integration was disconnected, reactivating also recovers in the background the Meta or TikTok leads that arrived during the pause (Google and LinkedIn catch up on their next poll); those recovered leads enter like any other. A WhatsApp line has one active source: reactivating a WhatsApp source whose line got another active source meanwhile fails with 409 lead_source_exists. Idempotent. Requires manage_sources. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_reactivateOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.reactivate".

Events it can emit

crm.lead.createdcrm.deal.created

Declared cost: up to 3 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/reactivate" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/reactivate" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Set who is notified of unassigned leads from a source

crm.lead_sources.update_no_rule_recipients

Chooses who gets the 'Lead received' notice (bell and email) for leads of this source that no assignment rule gives an owner: up to 10 people with access to the organization, never AI agents. An empty list goes back to the default, the account owner. Works on every source, including the system Manual source. Idempotent. Requires manage_sources.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_update_no_rule_recipientsOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.update_no_rule_recipients".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/no-rule-recipients" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "user_ids": [
    "USER_ID"
  ]
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/no-rule-recipients" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "user_ids": [
    "USER_ID"
  ]
}'

Set whether a returning contact opens new business

crm.lead_sources.update_returning_contact

Turns on or off 'every returning contact is new business' for a source: when on, a contact with closed history (a won or lost deal, an archived prospect) who comes back through this source opens a new prospect instead of returning to the closed record; open records are reused as always. Off is the default behavior. Works on every source, including the system Manual source. Idempotent. Requires manage_sources.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_update_returning_contactOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.update_returning_contact".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/returning-contact" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "enabled": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/returning-contact" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "enabled": true
}'

Turn AI scoring on or off for several lead sources

crm.lead_sources.bulk.update_ai_qualification

Turns automatic AI scoring on or off for up to 100 lead sources at once: with it off, the AI qualification of new and re-scored leads skips those sources (the manual Recalculate button still works). Works on system sources too. Ids that are not sources of the organization are skipped and returned in not_found_ids. Outside the app it runs as a dry run first and needs the confirm_token. Requires manage_sources.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_bulk_update_ai_qualificationOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.bulk.update_ai_qualification".

Declared cost: up to 100 reads and 100 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/bulk/ai-qualification" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source_ids": [
    "SOURCE_ID"
  ],
  "enabled": true,
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/bulk/ai-qualification" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source_ids": [
    "SOURCE_ID"
  ],
  "enabled": true,
  "dry_run": true
}'

Create a WhatsApp lead source on a connected line

crm.lead_sources.create_whatsapp

Creates the lead source of a WhatsApp line that is already connected (from crm.whatsapp.lines.available): every new chat on that number enters the CRM as a lead with the source's destination (prospect inbox or a pipeline deal), default pipeline, stage and labels, dedup strategy (merge, create_activity, notify, skip) and AI scoring. The pipeline, stage and labels must exist (a deal source needs its pipeline; without a stage, its first one). AI scoring of each lead consumes AI credits and stays off unless ai_qualification.enabled is sent true. It does not touch Meta: the line already brings its WhatsApp Business account and its webhook. Only CRM lines (409 whatsapp_line_not_crm), subscribed ones (409 whatsapp_line_not_subscribed) and one active source per line (409 lead_source_exists, details.lead_source_id). 404 external_account_not_linked when the line does not exist here. Delete it with crm.lead_sources.delete (the line keeps working for Messages, the Setter and the other modules that use it). Requires manage_sources.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_create_whatsappOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.create_whatsapp".

Declared cost: up to 2 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/whatsapp" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "whatsapp_line_id": "WHATSAPP_LINE_ID",
  "destination": "deal"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/whatsapp" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "whatsapp_line_id": "WHATSAPP_LINE_ID",
  "destination": "deal"
}'

Create a lead source from social DMs

crm.lead_sources.create_social_dm

Creates a lead source fed by direct messages of Social Inbox accounts of one platform (instagram, facebook for Messenger, tiktok): with dm_ingest_mode all, every new DM conversation from now on enters the CRM as a lead; with rules_only, only the ones the Social Inbox rules send. The lead follows the source's destination (prospect inbox or a pipeline deal), default pipeline and stage, dedup strategy and AI scoring (it consumes AI credits per lead). The pipeline, stage and labels must exist (a deal source needs its pipeline; without a stage, its first one). account_ids are the Social Inbox accounts of that platform (404 external_account_not_linked, details.platform, when one is not connected there). Requires manage_sources and edit access to the Social Inbox (and, with a key or an app, the social_inbox:write scope too).

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_create_social_dmOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.create_social_dm".

Declared cost: up to 6 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/social-dm" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "account_ids": [
    "ACCOUNT_ID"
  ],
  "dm_ingest_mode": "all",
  "destination": "deal",
  "deduplication": "merge",
  "ai_qualification": {},
  "platform": "instagram"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/social-dm" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "account_ids": [
    "ACCOUNT_ID"
  ],
  "dm_ingest_mode": "all",
  "destination": "deal",
  "deduplication": "merge",
  "ai_qualification": {},
  "platform": "instagram"
}'

Update a social DM lead source

crm.lead_sources.update_social_dm

Updates a DM lead source: its Social Inbox accounts, ingest mode, destination, default pipeline and stage, dedup strategy and AI scoring (send them all, as the source's dialog does). The pipeline, stage and labels must exist (a deal source needs its pipeline; without a stage, its first one). The platform does not change. Switching to dm_ingest_mode all for the first time sets the point from which conversations enter; later changes never re-import older ones. The system DM sources keep their name. 404 lead_source_not_found for a source that is not a DM source of this organization. Requires manage_sources and edit access to the Social Inbox (and, with a key or an app, the social_inbox:write scope too).

Scope

crm:write

Permission

Edit in the module · CRM action: manage_sources

MCP tool

crm_lead_sources_update_social_dmOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.update_social_dm".

Declared cost: up to 7 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/social-dm" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "NAME",
  "account_ids": [
    "ACCOUNT_ID"
  ],
  "dm_ingest_mode": "all",
  "destination": "deal",
  "deduplication": "merge",
  "ai_qualification": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/crm/lead-sources/{source_id}/social-dm" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "NAME",
  "account_ids": [
    "ACCOUNT_ID"
  ],
  "dm_ingest_mode": "all",
  "destination": "deal",
  "deduplication": "merge",
  "ai_qualification": {}
}'

Create a lead source from a person's bookings

crm.lead_sources.create_booking

Creates the lead source of a person's public booking page: each confirmed booking of that person (of one event type, event_type_id, or of all of them with all_event_types, also the ones published later) enters the CRM as a lead with the source's destination, default pipeline, stage and labels, field mapping of the booking form, dedup strategy and AI scoring; with use_assignment_rules the assignment rules choose the owner, otherwise it goes to that person. The pipeline, stage and labels must exist (a deal source needs its pipeline; without a stage, its first one). AI scoring of each lead consumes AI credits and stays off unless ai_qualification.enabled is sent true. Returns the id as source_id and id. One active source per event type and one all-event-types source per person (409 lead_source_exists). Errors: 400 event_type_required, 404 vendor_not_found (vendor_user_id is not a person of this organization), 404 event_type_not_found, 400 event_type_not_of_vendor. Requires full access to the CRM (manage_sources is not needed: a seller sets up the source of their own booking page).

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_lead_sources_create_bookingOn the full surface; on the compact one, mb_execute_operation with id: "crm.lead_sources.create_booking".

Declared cost: up to 52 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/booking" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "vendor_user_id": "VENDOR_USER_ID",
  "destination": "deal"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/lead-sources/booking" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "vendor_user_id": "VENDOR_USER_ID",
  "destination": "deal"
}'