People

List the messages of all of a person's conversations

crm.persons.messages.list

Lists the messages of every inbox conversation linked to a person (WhatsApp on any line and Instagram, Messenger or TikTok direct messages), newest first, in one call instead of one crm.messages.list per conversation, paginated by cursor (limit up to 200). Each message comes as in crm.messages.list (conversation_id, direction, content (the text), media, template, delivery status, who sent it, external_id), with attachments as links signed for one hour (media_urls_expire_at) and without the raw platform payload. Filters: since and until (epoch ms, both exclusive), channel (only the person's conversations of that channel) and direction (inbound: what the contacts wrote; outbound: what the house sent), the last one applied to the page that was read, so a page can bring fewer than limit while has_more is true (follow next_cursor). It reads the person's 30 conversations with the most recent activity: with more, conversations_truncated is true and the older conversations are left out (read them with crm.conversations.list with person_id and crm.messages.list). The same conversations crm.conversations.list shows are included: conversations on a line that belongs to another part of the product never are, and a seller with restricted scope only gets the conversations they own or those on lines they work. Not found (person_not_found) if the person does not exist or the seller cannot see them. Requires view_inbox. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).

Scope

crm:read

Permission

View the module · CRM action: view_inbox

MCP tool

crm_persons_messages_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.messages.list".

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

Parameters

Response

Errors

Example

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

List persons

crm.persons.list

Lists persons (contacts) most recently updated first, paginated by cursor; company_id keeps only the persons linked to that company. Each person carries their contactability: do_not_contact, unsubscribed_at, bounced_at, whatsapp_unreachable, and the name of their primary company as stored on their record (company_name). Archived persons 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. Use crm.persons.lookup to find one by email or phone. 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_persons_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.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/persons" \
  -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/persons" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one person

crm.persons.get

Returns a person with their emails, phones, companies (company_name: their primary company's name as stored on their record), owner, labels and custom fields, and whether they can be contacted: do_not_contact, unsubscribed_at (emails), bounced_at and whatsapp_unreachable (their number has no WhatsApp). Not found if the id does not exist or the seller's scope hides them. 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_persons_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.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/persons/{person_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/persons/{person_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a person with their company and deals

crm.persons.context

Returns the person, their primary company and their deals in one call: what you need to talk about them. deals are the deals where the person is linked or is the main contact (up to 50 of each), open, won and lost, not archived, open first and then the most recently moved. Not found if the person does not exist or is out of scope. 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_persons_contextOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.context".

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

Parameters

Response

Errors

Example

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

Find a person by email or phone (or many phones)

crm.persons.lookup

Finds the person that has the given email (any of their emails) or phone (normalized to E.164): person is the first one that is not a merged-away duplicate, by email first and then by phone, or null when there is no match or the seller's scope hides them. matches lists every record that has that email or that phone, not just one: the merged-away duplicates too (merged: true and merged_into_id, the record that remains), archived ones, and for the phone also the records that store it in another of its forms (the Argentine 9, the Mexican 1), each with matched_by (email, phone); up to 25 per value, only those the caller can see. phones (up to 30; by REST ?phones=a,b) looks up many numbers in one call: by_phone has one entry per number, in the order asked, with the number as asked, its E.164 form (normalized: null when it cannot be read as a phone with a country code, and then it is not looked up), person_id (the same rule as person) and its matches; person and matches stay those of email and phone. Use it before creating a person to avoid duplicates, and to find sibling records of a number before writing to 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 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_persons_lookupOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.lookup".

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

Parameters

Response

Errors

Example

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

Find prior deals and prospects that look like this contact

crm.persons.similar

Given a person and/or company (or a prospect, looked up by its person and company), returns the prior deals and prospects that look related: same person, a duplicate person with the same email or phone, the same company or another company on the same web domain. strong matches first. Use it before creating a deal or prospect to avoid working a contact twice.

Scope

crm:read

Permission

View the module

MCP tool

crm_persons_similarOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.similar".

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

Parameters

Response

Errors

Example

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

Create a person

crm.persons.create

Creates a person (contact) with name, emails, phones, job title, links, country, an optional company (becomes their primary company), owner, labels and custom fields; created: true. If a person already has the primary email (any of their emails), nothing is written: their id comes back with created: false and matched_by: email (a merged-away duplicate never comes back, the record that remains does; archived persons count). A seller with restricted scope who cannot see that person gets 409 person_exists_not_visible instead: their id never comes back and nothing is written. It does not deduplicate by phone: use crm.persons.lookup first. company_name is only the text shown on the record: it does not link a company (use company_id, from crm.companies.list or crm.companies.create, for that). Labels must be person labels (crm.labels.list with entity person: label_not_found otherwise), custom fields must exist for persons with a value of their type (custom_field_unknown, custom_field_invalid), the owner must be a member or an AI position (owner_not_member), and outside the screen every phone must be readable (with its country code or with country: invalid_phone otherwise). A new person fires the person_created sequence trigger, unless skip_automations is true (the audit log says what was skipped); the crm.person.created webhook fires either way. Requires create_person.

Scope

crm:write

Permission

Edit in the module · CRM action: create_person

MCP tool

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

Events it can emit

crm.person.created

Declared cost: up to 7 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/persons" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "first_name": "FIRST_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/persons" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "first_name": "FIRST_NAME"
}'

Mark one person as do-not-contact (or clear it)

crm.persons.set_do_not_contact

Sets do_not_contact on a person: send value or do_not_contact (the same flag, by the name it has on the person) with true to mark them, or with false to clear it and let them be contacted again. MB Suite stops starting the contact with a person marked «Do not contact»: sequences leave them out, the AI Setter does not write first (it still answers what they write), the voice agent does not call them, and a manual email, a WhatsApp template or an SMS to them is refused (409 do_not_contact) unless a person of the team confirms it on a closed basis (about their account, a charge or support, or because they asked us to write); a WhatsApp marketing template never goes to them. A reply to what they wrote after being marked still goes out, and so does WhatsApp free text (Meta only delivers it within 24 hours of their message). reason (optional, up to 500 characters) says why and is kept in the audit log of the change (the record has no field for it). Idempotent: if nothing changes, nothing is logged (changed: false). Requires edit_person.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_persons_set_do_not_contactOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.set_do_not_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/persons/{person_id}/do-not-contact" \
  -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/persons/{person_id}/do-not-contact" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Update a person

crm.persons.update

Updates one or more fields of a person: names, emails (the full list replaces; a single email is added), phones, job title, links, country, companies and primary company, owner, labels, custom fields, do-not-contact. A renamed person propagates their name to their deals and activities. Labels, custom fields, owner and phones are checked as in crm.persons.create. Returns the person as saved. Requires edit_person (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 records or 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_persons_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.update".

Events it can emit

crm.person.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/persons/{person_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/persons/{person_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a person

crm.persons.delete

Deletes a person. They go to the 30-day trash (restoring re-links them to the deals and lists they were removed from); their deals lose the link (the next person becomes primary) and their activities and conversations are kept. Prefer crm.persons.archive to just hide them. Requires delete_person.

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_person

MCP tool

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

Events it can emit

crm.person.deleted

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/crm/persons/{person_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/persons/{person_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Archive or unarchive a person

crm.persons.archive

Archives (archived: true) or restores (false) a person; archived persons leave the lists but keep everything. Idempotent: changed is false when they already were that way. Returns the person as they are now. Requires edit_person. 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:write

Permission

Edit in the module

MCP tool

crm_persons_archiveOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.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/persons/{person_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/persons/{person_id}/archive" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "archived": true
}'

Link a person to a company

crm.persons.companies.add

Adds a company to the person's companies; if they had none it becomes their primary company. Already linked: nothing is written (changed: false). Requires edit_person.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_persons_companies_addOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.companies.add".

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

Unlink a person from a company

crm.persons.companies.remove

Removes a company from the person's companies; if it was their primary company, the next one takes over. Not linked: nothing is written (changed: false). Requires edit_person.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_persons_companies_removeOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.companies.remove".

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/persons/{person_id}/companies/remove" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "company_id": "COMPANY_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/persons/{person_id}/companies/remove" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "company_id": "COMPANY_ID"
}'

Set the primary company of a person

crm.persons.set_primary_company

Makes a company the person's primary one (adding it to their companies if needed); their denormalized company name follows. Already the primary one: nothing is written (changed: false). Requires edit_person.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_persons_set_primary_companyOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.set_primary_company".

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/persons/{person_id}/companies/primary" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "company_id": "COMPANY_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/persons/{person_id}/companies/primary" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "company_id": "COMPANY_ID"
}'

Accept or dismiss a chat-data suggestion

crm.persons.chat_data.update

Resolves one suggestion that the person wrote in a chat (a phone, an email, a website): accept writes it to their record (a phone may need a country), dismiss hides it. The key and message_id come from the person's chat_data_suggestions. Requires edit_person.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_persons_chat_data_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.chat_data.update".

Declared cost: up to 2 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/persons/{person_id}/chat-data" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "KEY",
  "message_id": "MESSAGE_ID",
  "decision": "accept"
}'

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/persons/{person_id}/chat-data" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "KEY",
  "message_id": "MESSAGE_ID",
  "decision": "accept"
}'

Delete many persons

crm.persons.bulk.delete

Deletes up to 500 persons; each goes to the 30-day trash (restorable one by one) and leaves their deals and lists. deleted counts the persons that existed; the other ids come back in not_found. Requires bulk_delete_persons (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_persons

MCP tool

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

Events it can emit

crm.person.deleted

Declared cost: up to 2000 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/persons/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_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/persons/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "dry_run": true
}'

Add or remove labels on many persons

crm.persons.bulk.update_labels

Adds and/or removes labels (ids from crm.labels.list with entity person) on up to 500 persons; fires the label_added sequence trigger for the labels that are really new. A label that is not a person label of the organization is label_not_found (with details.unknown_ids). Persons 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 persons and names those that would change. Requires bulk_update_persons. 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_persons

MCP tool

crm_persons_bulk_update_labelsOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.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/persons/bulk/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_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/persons/bulk/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "dry_run": true
}'

Set the owner of many persons

crm.persons.bulk.update_owner

Sets (or clears with null) the owner of up to 500 persons: a member's user id (members.members.list) or an AI position's ai-… id (owner_not_member otherwise). Persons 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 persons and names those that would change. Requires bulk_update_persons. 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_persons

MCP tool

crm_persons_bulk_update_ownerOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.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/persons/bulk/owner" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_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/persons/bulk/owner" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "owner_id": "OWNER_ID",
  "dry_run": true
}'

Set the primary company of many persons

crm.persons.bulk.update_company

Makes a company the primary one of up to 500 persons (adding it to their companies), or clears the primary company with null without removing any. Persons that already have that primary company are left as they are (unchanged) and ids that do not exist are skipped (not_found). The dry run reads the same persons and names those that would change. Requires bulk_update_persons. 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_persons

MCP tool

crm_persons_bulk_update_companyOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.bulk.update_company".

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/persons/bulk/company" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "company_id": "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/persons/bulk/company" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "company_id": "COMPANY_ID",
  "dry_run": true
}'

Mark many persons as do-not-contact (or clear it)

crm.persons.bulk.set_do_not_contact

Sets do_not_contact on up to 500 persons (send value or do_not_contact, true or false), as crm.persons.set_do_not_contact does on one. MB Suite stops starting the contact with a person marked «Do not contact»: sequences leave them out, the AI Setter does not write first (it still answers what they write), the voice agent does not call them, and a manual email, a WhatsApp template or an SMS to them is refused (409 do_not_contact) unless a person of the team confirms it on a closed basis (about their account, a charge or support, or because they asked us to write); a WhatsApp marketing template never goes to them. A reply to what they wrote after being marked still goes out, and so does WhatsApp free text (Meta only delivers it within 24 hours of their message). Persons that already are that way are left as they are (unchanged) and ids that do not exist are skipped (not_found). The dry run reads the same persons and names those that would change. Requires bulk_update_persons. 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_persons

MCP tool

crm_persons_bulk_set_do_not_contactOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.bulk.set_do_not_contact".

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/persons/bulk/do-not-contact" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_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/persons/bulk/do-not-contact" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ],
  "dry_run": true
}'

List the sequence enrollments of a person

crm.persons.enrollments.list

Lists the sequence enrollments of one person across every sequence, newest first, paginated by cursor (limit up to 200), with the same fields as crm.sequences.enrollments.list (sequence_id, status, current step, pause and exit reasons, counters, last_history). Use it to know which sequences are writing to a contact before enrolling them in another one. Not found (person_not_found) if the person does not exist or a seller with restricted scope cannot see them. Requires view access to the CRM.

Scope

crm:read

Permission

View the module

MCP tool

crm_persons_enrollments_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.persons.enrollments.list".

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

Parameters

Response

Errors

Example

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