Prospectos

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).

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_prospects_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.list".

Custo declarado: até 201 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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).

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_prospects_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.get".

Custo declarado: até 2 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação. Nesta, só quando: 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).

Escopo

crm:write

Permissão

Editar no módulo · Ação do CRM: create_prospect

Tool do MCP

crm_prospects_createNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.create".

Eventos que pode emitir

crm.lead.created

Custo declarado: até 11 leituras e 4 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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).

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação. Nesta, só quando: the owner changes to an AI position (owner_id ai-…): its first turn runs right away and it may write to the lead.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_updateNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.update".

Custo declarado: até 89 leituras e 20 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_archiveNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.archive".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/archive" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_restoreNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.restore".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/restore" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_convertNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.convert".

Eventos que pode emitir

crm.deal.created

Custo declarado: até 10 leituras e 6 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.

Escopo

crm:write e «Permitir exclusões» (crm:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

crm_prospects_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.delete".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_bulk_archiveNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.bulk.archive".

Custo declarado: até 500 leituras e 500 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_bulk_update_interestNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.bulk.update_interest".

Custo declarado: até 501 leituras e 500 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_bulk_update_ownerNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.bulk.update_owner".

Custo declarado: até 500 leituras e 500 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_bulk_update_labelsNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.bulk.update_labels".

Custo declarado: até 540 leituras e 500 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write e «Permitir exclusões» (crm:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

crm_prospects_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.bulk.delete".

Custo declarado: até 500 leituras e 1000 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_prospects_interests_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.interests.list".

Custo declarado: até 50 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Sem parâmetros.

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_prospects_link_to_dealNa superfície completa; na compacta, mb_execute_operation com id: "crm.prospects.link_to_deal".

Custo declarado: até 6 leituras e 15 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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"
}'