Lists

List CRM lists

crm.lists.list

Lists the org's CRM lists (named groups of persons: static, dynamic or imported from a CSV), most recently updated first, paginated by cursor (limit up to 200). Filter by type. Each list carries its cached member_count and, if dynamic, its saved filter; member ids are not included: page through them with crm.lists.members.list.

Scope

crm:read

Permission

View the module

MCP tool

crm_lists_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.list".

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

Parameters

Response

Errors

Example

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

Get one CRM list

crm.lists.get

Returns a CRM list: name, description, type (static, dynamic or csv), color, icon, the cached member_count and when it was last counted, the saved filter of a dynamic list, the CSV import summary, owner (with owner_name) and dates. Member ids are not included by default; page through the members with crm.lists.members.list. With include_member_ids=true a static or csv list also returns person_ids: the saved ids exactly as stored, in order, including persons deleted or merged away since (useful to clean a list: crm.lists.members.list only returns the ones that still exist). Never for a dynamic list (it saves no ids) nor for a seller restricted to their own records (they page through crm.lists.members.list, which applies their scope): then person_ids does not come. The list is already read; resolving the owner's name may read their profile.

Scope

crm:read

Permission

View the module

MCP tool

crm_lists_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.get".

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

Parameters

Response

Errors

Example

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

List the members of a CRM list

crm.lists.members.list

Returns the persons in a list ordered by person id, paginated by cursor (limit up to 200). Static and CSV lists return their saved persons that still exist; a dynamic list applies its saved filter to the org's persons, scanning at most 2,000 persons per call (with labels or owners in the filter, only the persons that have them are scanned). Archived persons are left out unless include_archived is true, and merged-away duplicates never appear. Deleted or archived persons, persons outside a restricted seller's scope and that scan limit can leave a page with fewer members than limit (even none) while has_more is true: keep following 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_lists_members_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.members.list".

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

Parameters

Response

Errors

Example

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

Create a CRM list

crm.lists.create

Creates a list of persons, owned by the caller: static (person_ids, up to 5,000; a repeated id is saved and counted once, and an id that is not a person of the organization is not saved: it comes back in not_found), dynamic (a saved filter over persons: search text, company_ids, label_ids with label_mode any/all, owner_ids, countries, do_not_contact included/excluded, created_after) or csv (behaves like static; importing a CSV file is not part of this operation). The member count is computed on creation: for a static or csv list, the distinct ids that are persons of the organization; for a dynamic list, every person that matches the filter, archived persons and merged-away duplicates included (crm.lists.members.list leaves those out). Optional dry run: with dry_run=true nothing is written; it counts exactly as the creation and its preview says how many persons the list would start with (counts lists, member_count and, for a static or csv list, requested, the distinct ids sent, and not_found, the ones that are not persons of the organization), with up to 50 of the counted persons as items (id and name; a person outside a restricted seller's scope comes without their name; none for a dynamic list without criteria, which is every person and is counted without reading them) and a warning when ids came repeated or the count reached its limit of 30,000. Running the creation needs no confirm_token. The declared cost is the worst case (a dynamic list scans up to 30,000 persons); a call is charged what it really reads: a static list of N persons, N reads; an empty one, none. Requires create_list.

Scope

crm:write

Permission

Edit in the module · CRM action: create_list

MCP tool

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

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

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

Update a CRM list

crm.lists.update

Updates the name, description, color, icon or sharing flag of a list (null clears description, color or icon) and, for a dynamic list only, its saved filter, which recomputes the member count. Send the fields at the top level or inside updates (not both: updates_conflict). Members of a static list change with crm.lists.members.add and crm.lists.members.remove. Returns the list as saved and changed: false when it already was that way (nothing written). Requires edit_list (a seller edits their own lists and the ones without owner).

Scope

crm:write

Permission

Edit in the module

MCP tool

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

Declared cost: up to 30001 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/lists/{list_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 PATCH "https://api.mb-suite.com/v1/crm/lists/{list_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Duplicate a CRM list

crm.lists.duplicate

Creates a copy of a list named after it with the suffix in the caller's language: '(copia)', '(copy)' or '(cópia)', owned by the caller, with the same type, description, color, icon, members or filter, CSV summary and cached member count. The original is not touched. Requires create_list.

Scope

crm:write

Permission

Edit in the module · CRM action: create_list

MCP tool

crm_lists_duplicateOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.duplicate".

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/lists/{list_id}/duplicate" \
  -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/lists/{list_id}/duplicate" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a CRM list

crm.lists.delete

Deletes a list; the persons in it are not touched. The sequences that auto-enrolled from it lose that link (the result says how many). The list goes to the 30-day trash: restoring it brings the list back, not its links to sequences. Requires delete_list (a seller deletes their own lists and the ones without owner).

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_lists_deleteOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.delete".

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

Parameters

Response

Errors

Example

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

Add persons to a static list

crm.lists.members.add

Adds up to 2,000 persons (ids from crm.persons.list or crm.persons.lookup) to a static or CSV list; ids already in the list are ignored, ids that are not persons of the organization are not added (not_found), and the result says how many were added and the new member count. Sequences triggered by 'added to a list' start for the persons actually added. Not for dynamic lists, whose members come from their filter. Requires edit_list.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_lists_members_addOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.members.add".

Declared cost: up to 2001 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/lists/{list_id}/members" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_ids": [
    "PERSON_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/lists/{list_id}/members" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ]
}'

Remove persons from a static list

crm.lists.members.remove

Removes up to 2,000 persons from a static or CSV list; ids that are not in the list are ignored and the result says how many were removed and the new member count (an old stored id that is not a person is removed without changing the count). The persons themselves are not deleted. Not for dynamic lists. Requires edit_list.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_lists_members_removeOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.members.remove".

Declared cost: up to 2001 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/lists/{list_id}/members/remove" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_ids": [
    "PERSON_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/lists/{list_id}/members/remove" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_ids": [
    "PERSON_ID"
  ]
}'

Recount the members of a list

crm.lists.refresh_count

Recomputes and saves the cached member_count of a list: the saved persons that still exist, each once (static, csv), or the persons that match its filter now, archived persons and merged-away duplicates included (dynamic). Changes nothing else and leaves no audit entry (it is equivalent to a read). Idempotent. Optional dry run: with dry_run=true it counts the same way without saving, and its preview says the number (counts lists, member_count, the count now, and previous_member_count, the cached one) with up to 50 of the counted persons as items; running needs no confirm_token. The declared cost is the worst case (a dynamic list scans up to 30,000 persons); a call is charged what it really reads: the list plus its N saved persons for a static list. Any member with access to the CRM can run it.

Scope

crm:write

Permission

View the module

MCP tool

crm_lists_refresh_countOn the full surface; on the compact one, mb_execute_operation with id: "crm.lists.refresh_count".

Declared cost: up to 30001 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/lists/{list_id}/refresh-count" \
  -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/lists/{list_id}/refresh-count" \
  -H "Authorization: Bearer $MB_TEST_KEY"