Prospects

List prospects (inbox)

crm.prospects.list

Lists prospects newest first, paginated by cursor. status: active (new + reviewing, the inbox; default), archived, converted or all. person_id keeps the prospects of one person and owner_id those of one owner (a member, or an AI agent's ai-… id); with both, the owner is applied to the page read. A seller with restricted scope only gets their own, the unassigned ones and the AI's, applied to the page read, so a page can bring fewer than limit while has_more is true: follow next_cursor until has_more is false. 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_prospects_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/prospects" \
  -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/prospects" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one prospect

crm.prospects.get

Returns a prospect with its status (lifecycle), interest, linked person and company, value, owner, source, attribution, labels and custom fields. Not found if the id does not exist or the seller's scope hides it. 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_prospects_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.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/prospects/{prospect_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/prospects/{prospect_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a prospect

crm.prospects.create

Creates a prospect in the inbox (status new). Link it to an existing person/company by id, or pass person {full_name, email, phone, company_name} and the person and company are created or reused (dedup by email and phone). Without an owner, the Manual source's assignment rule applies if there is one; without a rule, the prospect goes to the owner of its person when they are a member of the organization (not a viewer), and otherwise it is left unassigned (owner_id null), visible to the whole team. Requires create_prospect. A seller with restricted scope can only link, by id, a person and a company they can already see (their own, unassigned, or of a deal of theirs); any other is not found (person_not_found, company_not_found), before anything is written. If they end up as the owner (chosen, or by the Manual source's assignment rule) and the person or company found by person belongs to someone else, outside what they can see, it is denied with 403 prospect_contact_not_visible and no prospect is created; and the response leaves out the person_id and company_id of a contact they cannot see. With an AI position as owner (owner_id ai-…) the agent answers the lead's messages by itself (AI on each one) and may write to them: outside the app that needs a dry run and its confirm_token, like handing a prospect to an AI position with crm.prospects.update; any other owner runs directly.

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. In this one, only when: the owner is an AI position (owner_id ai-…): from then on the agent answers the lead's messages by itself, with AI on each one, and may write to them (as when crm.prospects.update hands a prospect to an AI position).

Scope

crm:write

Permission

Edit in the module · CRM action: create_prospect

MCP tool

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

Events it can emit

crm.lead.created

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "TITLE",
  "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/prospects" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "TITLE",
  "dry_run": true
}'

Update a prospect

crm.prospects.update

Updates one or more fields of a prospect: title, interest (its visible status), value, currency, expected close date, owner (only a Manager can transfer; others' owner_id is ignored), labels, custom fields, the ad platform's external_lead_id (null clears it) and is_starred. Changes go to the prospect's changelog. Making an AI position (ai-…) the owner starts its first turn right away (it may write to the lead; not when the prospect's person is marked «Do not contact» or unsubscribed: the AI never writes first to them and waits, with next_run_reason do_not_contact, until they write) and counts as one AI call: outside the app that change needs a dry run and its confirm_token (any other update runs directly), and in the practice organization of test keys it fails with 409 sandbox_external_unavailable and nothing changes. Without AI credits for that first turn in the organization's pool (or with the subscription that pays them blocked), the turn does not call the AI and writes to no one: the prospect goes at once to the position's escalation person (or to whoever the lead source's assignment rule picks), and the prospect returned already shows that person as its owner. Requires edit_prospect (a seller edits their own and the unassigned ones). 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).

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. In this one, only when: the owner changes to an AI position (owner_id ai-…): its first turn runs right away and it may write to the lead.

Scope

crm:write

Permission

Edit in the module

MCP tool

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

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

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {},
  "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 PATCH "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {},
  "dry_run": true
}'

Archive a prospect

crm.prospects.archive

Archives a prospect (status archived, optional reason): it leaves the inbox and keeps everything; crm.prospects.restore brings it back. Idempotent: changed is false when it already was archived (with that reason). Requires archive_prospect.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_prospects_archiveOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.archive".

Declared cost: up to 1 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/prospects/{prospect_id}/archive" \
  -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/prospects/{prospect_id}/archive" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Restore an archived prospect to the inbox

crm.prospects.restore

Brings an archived prospect back to the inbox (status reviewing) and clears the archive data. Idempotent: a prospect that is not archived is left as is (changed: false). Requires archive_prospect.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_prospects_restoreOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.restore".

Declared cost: up to 1 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/prospects/{prospect_id}/restore" \
  -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/prospects/{prospect_id}/restore" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Convert a prospect into a deal

crm.prospects.convert

Creates a deal from the prospect in the given pipeline and stage, assigned to owner_id (a member), with optional title/value/currency overrides; the prospect becomes converted and its activities and conversations move to the deal. Idempotent: an already converted prospect returns its deal. Requires convert_prospect. A seller with restricted scope cannot convert a prospect that is not theirs when its person or company belongs to someone else and is outside what they can see (their own, unassigned, or of a deal of theirs): 403 prospect_contact_not_visible and no deal is created; a Manager or an Admin converts it, or assigns it to them first.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_prospects_convertOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.convert".

Events it can emit

crm.deal.created

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/convert" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "pipeline_id": "PIPELINE_ID",
  "stage_id": "STAGE_ID",
  "owner_id": "OWNER_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/prospects/{prospect_id}/convert" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "pipeline_id": "PIPELINE_ID",
  "stage_id": "STAGE_ID",
  "owner_id": "OWNER_ID"
}'

Delete a prospect

crm.prospects.delete

Deletes a prospect; it goes to the 30-day trash. Its person, company and activities are kept. Prefer crm.prospects.archive to just take it out of the inbox. Requires delete_prospect.

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

MCP tool

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

Declared cost: up to 1 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/prospects/{prospect_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/prospects/{prospect_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Archive many prospects

crm.prospects.bulk.archive

Archives up to 500 prospects with an optional reason. Prospects already archived are left as they are (unchanged) and ids that do not exist are skipped (not_found). A Manager archives any; a seller only their own and the unassigned ones (one foreign id rejects the whole batch with prospects_not_owned). The dry run reads the same prospects and names those that would be archived. Outside the screen it requires a dry run and a confirm_token.

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

MCP tool

crm_prospects_bulk_archiveOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.bulk.archive".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/archive" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "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/prospects/bulk/archive" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "dry_run": true
}'

Set the interest (visible status) of many prospects

crm.prospects.bulk.update_interest

Sets the interest (the status the inbox shows) of up to 500 prospects. interest_id must be one of crm.prospects.interests.list (any other is interest_not_found). Prospects that already have it are left as they are (unchanged) and ids that do not exist are skipped (not_found). A Manager updates any; a seller only their own and the unassigned ones (prospects_not_owned otherwise). The dry run reads the same prospects. Outside the screen it requires a dry run and a confirm_token.

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

MCP tool

crm_prospects_bulk_update_interestOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.bulk.update_interest".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/interest" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "interest_id": "INTEREST_ID",
  "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/prospects/bulk/interest" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "interest_id": "INTEREST_ID",
  "dry_run": true
}'

Assign many prospects to an owner

crm.prospects.bulk.update_owner

Assigns up to 500 prospects to a member (owner_id, from members.members.list or crm.team.list; null clears the owner) and notifies the new owner once. An AI position is assigned one prospect at a time with crm.prospects.update (it starts its first turn). Prospects that already have that owner are left as they are (unchanged) and ids that do not exist are skipped (not_found). The dry run reads the same prospects. Manager-tier only. Outside the screen it requires a dry run and a confirm_token.

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

MCP tool

crm_prospects_bulk_update_ownerOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.bulk.update_owner".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/owner" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "owner_id": "OWNER_ID",
  "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/prospects/bulk/owner" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "owner_id": "OWNER_ID",
  "dry_run": true
}'

Add or remove labels on many prospects

crm.prospects.bulk.update_labels

Adds and/or removes labels (ids from crm.labels.list with entity prospect) on up to 500 prospects. A label that is not a prospect label of the organization is label_not_found. Prospects that already have exactly those labels are left as they are (unchanged) and ids that do not exist are skipped (not_found). A Manager updates any; a seller only their own and the unassigned ones. The dry run reads the same prospects. Outside the screen it requires a dry run and a confirm_token.

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

MCP tool

crm_prospects_bulk_update_labelsOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.bulk.update_labels".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "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/prospects/bulk/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "dry_run": true
}'

Delete many prospects

crm.prospects.bulk.delete

Deletes up to 500 prospects; each goes to the 30-day trash and can be restored one by one. Requires bulk_delete_prospects (Manager-tier). Outside the screen it requires a dry run and a confirm_token.

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 and “Allow deletions” (crm:delete in OAuth)

Permission

Edit in the module

MCP tool

crm_prospects_bulk_deleteOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.bulk.delete".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "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/prospects/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "dry_run": true
}'

List the prospect statuses (interests)

crm.prospects.interests.list

Lists the statuses a prospect can have in the inbox (called interests in the API: interested, cold… and the ones the organization added), in their order, with id, name and color. interest_id of crm.prospects.create, crm.prospects.update and crm.prospects.bulk.update_interest is one of these ids.

Scope

crm:read

Permission

View the module

MCP tool

crm_prospects_interests_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.interests.list".

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

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/prospects/interests" \
  -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/prospects/interests" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Link a prospect to an existing deal

crm.prospects.link_to_deal

Instead of creating a new deal, attaches the prospect to an existing one: its person joins the deal (and becomes primary if the deal had none), its history moves to the deal and the prospect becomes converted. The deal must not be merged and the prospect must still be open. Requires edit_deal. A seller with restricted scope cannot use it for a prospect that is not theirs when its person or company belongs to someone else and is outside what they can see: 403 prospect_contact_not_visible, as in crm.prospects.convert.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_prospects_link_to_dealOn the full surface; on the compact one, mb_execute_operation with id: "crm.prospects.link_to_deal".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/link-to-deal" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "deal_id": "DEAL_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/prospects/{prospect_id}/link-to-deal" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "deal_id": "DEAL_ID"
}'