API reference · CRM

Labels

crm · labels · 6 operations

GET/v1/crm/labelsList the labels of one entity type POST/v1/crm/labelsCreate a label for one entity type PATCH/v1/crm/labels/{label_id}Rename, recolor or move a label POST/v1/crm/labels/reorderSet the order of the labels of one entity type DELETE/v1/crm/labels/{label_id}Delete a label POST/v1/crm/labels/assignSet, add or remove labels on conversations

GET/v1/crm/labels

List the labels of one entity type

crm.labels.list

ReadIdempotentSince 2026-11-01

Lists the labels (id, name, color, order) the org defined for one entity: deal, person, company, prospect, conversation or sequence. Each entity has its own pool: a person label cannot be put on a deal. Use the ids in label_ids when creating or updating records.

Scope: crm:read
Permission: View the module
MCP tool: crm_labels_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.labels.list".

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

Parameters

entityenumqueryrequired

Whose labels: each kind of record has its own pool.

Values: deal, person, company, prospect, conversation, sequence

Response

dataarray<object>

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

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

POST/v1/crm/labels

Create a label for one entity type

crm.labels.create

WriteSince 2026-11-01

Creates a label in the pool of one entity (deal, person, company, prospect, conversation or sequence) with a name (up to 60 characters) and a color (a hex such as #22c55e). It goes last in the order and its creator is recorded: a seller can later rename or delete only the labels they created; Managers and admins, all of them. Requires manage_labels, which every member except viewers has.

Scope: crm:write
Permission: Edit in the module · CRM action: manage_labels
MCP tool: crm_labels_createOn the full surface; on the compact one, mb_execute_operation with id: "crm.labels.create".

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

Parameters

entityenumbodyrequired

The kind of record whose labels these are: each one has its own pool.

Values: deal, person, company, prospect, conversation, sequence

namestringbodyrequired

The label's name, up to 60 characters.

colorstringbodyrequired

A hex color: #22c55e. The app's palette: #ef4444, #f97316, #eab308, #22c55e, #10b981, #06b6d4, #3b82f6, #8b5cf6, #ec4899, #6b7280.

Response

label_idstring

Errors

crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

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

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

PATCH/v1/crm/labels/{label_id}

Rename, recolor or move a label

crm.labels.update

WriteIdempotentSince 2026-11-01

Updates the name, color (a hex such as #22c55e) or order of a label of one entity (deal, person, company, prospect, conversation or sequence); send at least one of them, at the top level or inside updates (not both: updates_conflict). The records that carry the label keep it. Returns the label as saved and changed: false when it already was that way (nothing written). A seller can only edit the labels they created (or old ones without an author); Managers and admins, any. Use crm.labels.reorder to set the whole order at once. Requires manage_labels.

Scope: crm:write
Permission: Edit in the module
MCP tool: crm_labels_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.labels.update".

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

Parameters

label_idstringpathrequired

The label, by id (crm.labels.list).

entityenumbodyrequired

The kind of record whose labels these are: each one has its own pool.

Values: deal, person, company, prospect, conversation, sequence

namestringbodyoptional

The label's name, up to 60 characters.

colorstringbodyoptional

A hex color: #22c55e. The app's palette: #ef4444, #f97316, #eab308, #22c55e, #10b981, #06b6d4, #3b82f6, #8b5cf6, #ec4899, #6b7280.

orderintegerbodyoptional

Its position among the labels of that entity (0 first).

updatesobjectbodyoptional

The same fields, grouped as in the other CRM edits (crm.deals.update…): send them here or at the top level, not both.

Response

oktrue

changedboolean

false when the label already was that way: nothing was written.

labelobject

Errors

label_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

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

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/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entity": "deal"
}'

POST/v1/crm/labels/reorder

Set the order of the labels of one entity type

crm.labels.reorder

WriteIdempotentSince 2026-11-01

Sets the display order of the labels of one entity (deal, person, company, prospect, conversation or sequence): each id in ordered_ids (up to 200) gets its position as order. Every id must be a label of that entity, otherwise nothing is reordered (label_not_found, with the ids that are not in details.unknown_ids). It does not create, rename or delete labels. Requires manage_labels.

Scope: crm:write
Permission: Edit in the module · CRM action: manage_labels
MCP tool: crm_labels_reorderOn the full surface; on the compact one, mb_execute_operation with id: "crm.labels.reorder".

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

Parameters

entityenumbodyrequired

The kind of record whose labels these are: each one has its own pool.

Values: deal, person, company, prospect, conversation, sequence

ordered_idsarray<string>bodyrequired

The label ids in the order they should have (each one gets its position as order).

Response

oktrue

Errors

crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/crm/labels/reorder" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity": "deal",
  "ordered_ids": [
    "ORDERED_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/labels/reorder" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity": "deal",
  "ordered_ids": [
    "ORDERED_ID"
  ]
}'

DELETE/v1/crm/labels/{label_id}

Delete a label

crm.labels.delete

IrreversibleSince 2026-11-01

Deletes a label of one entity (deal, person, company, prospect, conversation or sequence) and removes it from every record that carried it. The label goes to the 30-day trash with the ids of the records that had it, and restoring it puts it back on them (the trash keeps up to 5,000 ids: with more, the trash item says linked_truncated and the dry run warns); the records themselves are not touched otherwise and no webhook event is sent for them. A seller can only delete the labels they created (or old ones without an author); Managers and admins, any. Requires manage_labels. Outside the screen it requires a dry run and a confirm_token.

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

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

Parameters

label_idstringpathrequired

The label, by id (crm.labels.list).

entityenumbodyrequired

The kind of record whose labels these are: each one has its own pool.

Values: deal, person, company, prospect, conversation, sequence

Response

oktrue

trash_item_idstring

The trash item this deletion left: the item_id of platform.trash.restore (POST /trash/{item_id}/restore). Missing if nothing went to the trash.

trash_item_idsarray<string>

Only when the deletion left more than one copy: all of them, the first being trash_item_id.

trash_expires_atnumber

When the copy leaves the trash for good (epoch ms): 30 days after the deletion.

Errors

label_not_found delete_not_allowed confirmation_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

curl -X DELETE "https://api.mb-suite.com/v1/crm/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entity": "deal"
}'

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/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entity": "deal"
}'

POST/v1/crm/labels/assign

Set, add or remove labels on conversations

crm.labels.assign

WriteBulk · up to 500IdempotentSince 2026-11-01

Labels up to 500 inbox conversations at once (entity: conversation, which can be left out; label ids from crm.labels.list with entity conversation). Send label_ids to replace the whole set, or to_add / to_remove to add or remove labels while keeping the rest. A label that is not a conversation label of the organization is label_not_found (with details.unknown_ids), in the dry run too. Only the conversations the caller can see in crm.conversations.list are labeled (not those on another module's line and, for a seller with restricted scope, only theirs or those on lines they work): the rest, and ids that do not exist, come back in not_found and are left untouched; updated counts the labeled ones. Deals, persons, companies and prospects are labeled with their own update or bulk.update_labels operations instead. Requires full access to the CRM. Bulk: 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
MCP tool: crm_labels_assignOn the full surface; on the compact one, mb_execute_operation with id: "crm.labels.assign".

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

Parameters

conversation_idsarray<string>bodyrequired

The inbox conversations to label (crm.conversations.list).

entityenumbodyoptional

Always conversation (the only kind labeled here); it can be left out.

Values: conversation · Default: "conversation"

label_idsarray<string>bodyoptional

The whole set of labels each conversation ends up with (replaces what they had).

to_addarray<string>bodyoptional

Labels to add, keeping the rest.

to_removearray<string>bodyoptional

Labels to remove, keeping the rest.

Response

oktrue

updatednumber

not_foundarray<string>

Errors

confirmation_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/crm/labels/assign" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_ids": [
    "CONVERSATION_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/labels/assign" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_ids": [
    "CONVERSATION_ID"
  ],
  "dry_run": true
}'