Referência da API · CRM

Etiquetas

crm · labels · 6 operações

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

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

Escopo: crm:read
Permissão: Ver o módulo
Tool do MCP: crm_labels_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.list".

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

Parâmetros

entityenumqueryobrigatório

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

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

Resposta

dataarray<object>

Erros

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

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

POST/v1/crm/labels

Create a label for one entity type

crm.labels.create

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

Escopo: crm:write
Permissão: Editar no módulo · Ação do CRM: manage_labels
Tool do MCP: crm_labels_createNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.create".

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

Parâmetros

entityenumcorpoobrigatório

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

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

namestringcorpoobrigatório

The label's name, up to 60 characters.

colorstringcorpoobrigatório

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

Resposta

label_idstring

Erros

crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Exemplo

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

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

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

Escopo: crm:write
Permissão: Editar no módulo
Tool do MCP: crm_labels_updateNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.update".

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

Parâmetros

label_idstringrotaobrigatório

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

entityenumcorpoobrigatório

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

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

namestringcorpoopcional

The label's name, up to 60 characters.

colorstringcorpoopcional

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

orderintegercorpoopcional

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

updatesobjectcorpoopcional

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

Resposta

oktrue

changedboolean

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

labelobject

Erros

label_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

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

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

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

Escopo: crm:write
Permissão: Editar no módulo · Ação do CRM: manage_labels
Tool do MCP: crm_labels_reorderNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.reorder".

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

Parâmetros

entityenumcorpoobrigatório

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

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

ordered_idsarray<string>corpoobrigatório

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

Resposta

oktrue

Erros

crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Exemplo

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"
  ]
}'

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

IrreversívelDesde 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.

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
Tool do MCP: crm_labels_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.delete".

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

Parâmetros

label_idstringrotaobrigatório

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

entityenumcorpoobrigatório

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

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

Resposta

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.

Erros

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

Exemplo

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

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

EscritaEm massa · até 500IdempotenteDesde 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.

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
Tool do MCP: crm_labels_assignNa superfície completa; na compacta, mb_execute_operation com id: "crm.labels.assign".

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

Parâmetros

conversation_idsarray<string>corpoobrigatório

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

entityenumcorpoopcional

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

Valores: conversation · Padrão: "conversation"

label_idsarray<string>corpoopcional

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

to_addarray<string>corpoopcional

Labels to add, keeping the rest.

to_removearray<string>corpoopcional

Labels to remove, keeping the rest.

Resposta

oktrue

updatednumber

not_foundarray<string>

Erros

confirmation_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

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

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/labels/assign" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_ids": [
    "CONVERSATION_ID"
  ],
  "dry_run": true
}'