Companies

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

Scope

crm:read

Permission

View the module

MCP tool

crm_companies_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.companies.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/companies" \
  -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/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).

Scope

crm:read

Permission

View the module

MCP tool

crm_companies_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.companies.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/companies/{company_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/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.

Scope

crm:write

Permission

Edit in the module · CRM action: create_company

MCP tool

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

Events it can emit

crm.company.created

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

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

Scope

crm:write

Permission

Edit in the module

MCP tool

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

Events it can emit

crm.company.updated

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

Parameters

Response

Errors

Example

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

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

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: delete_company

MCP tool

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

Events it can emit

crm.company.deleted

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/companies/{company_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/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).

Scope

crm:write

Permission

Edit in the module

MCP tool

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

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/companies/{company_id}/archive" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "archived": 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/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.

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 · CRM action: bulk_delete_companies

MCP tool

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

Events it can emit

crm.company.deleted

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/companies/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_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/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.

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: bulk_update_companies

MCP tool

crm_companies_bulk_update_labelsOn the full surface; on the compact one, mb_execute_operation with id: "crm.companies.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/companies/bulk/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_ids": [
    "COMPANY_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/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.

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: bulk_update_companies

MCP tool

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

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

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