Empresas

List companies

crm.companies.list

Lists companies most recently updated first, paginated by cursor; domain keeps only the companies with that domain (a host or a URL: https://www.acme.com/about → acme.com; one stored as www.acme.com matches too; 400 invalid_domain when no host can be read from it). Archived companies are left out unless include_archived is true; merged-away duplicates never appear. A seller with restricted scope only gets their own, the free ones and those of their deals. Both filters apply 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_companies_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.companies.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/companies" \
  -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/companies" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one company

crm.companies.get

Returns a company with its domain, industry, size, contact data, owner, labels, custom fields and aggregates: person_count (live persons), open_deal_count, won_deal_count and total_won_value in total_won_currency (deals won in other currencies are in won_value_by_currency, never added together), kept up to date when its deals and persons change. 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_companies_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.companies.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/companies/{company_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/companies/{company_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a company

crm.companies.create

Creates a company with name, domain, industry, size, website, country, phones, emails, owner, labels and custom fields; created: true. The domain is stored as a bare host (https://www.Acme.com/ → acme.com); without one, it is taken from website when that is a business domain (never a free email provider, a social network or a no-website answer like notengo.com). If a company with the same name already exists (ignoring case, accents, extra spaces and punctuation: Ñandú, nandu and ÑANDÚ are the same), nothing is written: its id comes back with created: false and matched_by: name. With dedupe_by_domain: true, a company with the same domain (www. or not) is reused the same way (matched_by: domain); by default it is not, as in the app, because subsidiaries share a domain. A merged-away duplicate never comes back (the company that remains does); archived companies count. A seller with restricted scope who cannot see that company gets 409 company_exists_not_visible instead (param name, or domain/website with dedupe_by_domain): its id never comes back and nothing is written. The owner must be a member or an AI position (owner_not_member), labels must be company labels (label_not_found), custom fields must exist for companies with a value of their type (custom_field_unknown, custom_field_invalid), and outside the screen every phone must be readable (with its country code or with country: invalid_phone). Requires create_company.

Escopo

crm:write

Permissão

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

Tool do MCP

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

Eventos que pode emitir

crm.company.created

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

Parâmetros

Resposta

Erros

Exemplo

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

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/companies" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Update a company

crm.companies.update

Updates one or more fields of a company; a renamed company propagates its name to its deals (company_name, up to 500) and activities, as in the app. It does NOT rewrite the company_name stored on its persons (the app does not either): to change it there, use crm.persons.update or crm.persons.set_primary_company. The domain is stored as a bare host (https://www.Acme.com/ → acme.com; null clears it); setting website on a company without a domain also fills its domain when website is a business one. is_placeholder: false confirms a provisional company (created by an automatic intake and named after the person or the phone); editing other fields does not confirm it, renaming it to a real name does, and the audit log records the confirmation. is_placeholder: false alone on a company that is not provisional writes nothing (no audit, no webhook, updated_at unchanged) and returns the company as it is. Requires edit_company (a seller edits their own, the free ones and those of their deals). 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:write

Permissão

Editar no módulo

Tool do MCP

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

Eventos que pode emitir

crm.company.updated

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

Parâmetros

Resposta

Erros

Exemplo

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

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/companies/{company_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a company

crm.companies.delete

Deletes a company (its persons and deals keep their references and are not deleted; use crm.delete_cascade for that). It goes to the 30-day trash. Requires delete_company.

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 · Ação do CRM: delete_company

Tool do MCP

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

Eventos que pode emitir

crm.company.deleted

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/companies/{company_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/companies/{company_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Archive or unarchive a company

crm.companies.archive

Archives (archived: true) or restores (false) a company; archived companies leave the lists but keep everything. Idempotent: changed is false when it already was that way. Returns the company as it is now. Requires edit_company. 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:write

Permissão

Editar no módulo

Tool do MCP

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

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/companies/{company_id}/archive" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "archived": 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/companies/{company_id}/archive" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "archived": true
}'

Delete many companies

crm.companies.bulk.delete

Deletes up to 500 companies; each goes to the 30-day trash (their persons and deals keep their references). deleted counts the companies that existed; the other ids come back in not_found. Requires bulk_delete_companies (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 · Ação do CRM: bulk_delete_companies

Tool do MCP

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

Eventos que pode emitir

crm.company.deleted

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/companies/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_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/companies/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_ID"
  ],
  "dry_run": true
}'

Add or remove labels on many companies

crm.companies.bulk.update_labels

Adds and/or removes labels (ids from crm.labels.list with entity company) on up to 500 companies. A label that is not a company label of the organization is label_not_found (with details.unknown_ids). Companies that already have exactly those labels are left as they are (unchanged) and ids that do not exist are skipped (not_found). The dry run reads the same companies and names those that would change. Requires bulk_update_companies. 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 · Ação do CRM: bulk_update_companies

Tool do MCP

crm_companies_bulk_update_labelsNa superfície completa; na compacta, mb_execute_operation com id: "crm.companies.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/companies/bulk/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_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/companies/bulk/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_ID"
  ],
  "dry_run": true
}'

Set the owner of many companies

crm.companies.bulk.update_owner

Sets (or clears with null) the owner of up to 500 companies: a member's user id (members.members.list) or an AI position's ai-… id (owner_not_member otherwise). Companies 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 companies and names those that would change. Requires bulk_update_companies. 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 · Ação do CRM: bulk_update_companies

Tool do MCP

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

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/companies/bulk/owner" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_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/companies/bulk/owner" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_ID"
  ],
  "owner_id": "OWNER_ID",
  "dry_run": true
}'