MB SuiteMB Suite
Menu

Referência da API · CRM

Campos personalizados

crm · custom_fields · 4 operações

GET/v1/crm/custom-fieldsPOST/v1/crm/custom-fieldsPATCH/v1/crm/custom-fields/{field_id}DELETE/v1/crm/custom-fields/{field_id}
GET/v1/crm/custom-fields

List custom field definitions

crm.custom_fields.list

LeituraIdempotenteDesde 2026-11-01

Lists the custom fields defined in the org (name, slug, type, options, required, group, visibility), optionally for one entity: deal, person, company, prospect or product. The slug is the key used in each record's custom_fields.

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

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

Parâmetros

entityenumqueryopcional

Only the fields of this kind of record; without it, all of them.

Valores: deal, person, company, prospect, product

Resposta

dataarray<object>

Erros

invalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Exemplo

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

Create a custom field

crm.custom_fields.create

EscritaDesde 2026-11-01

Defines a custom field for an entity with a type (text, number, currency, date, select, multiselect, url, email, phone, checkbox, user, rating, progress, files…), options for selects, required flag, help text, group and visibility. The slug (lowercase, digits, underscore) is derived from the name unless given and must be unique per entity. Requires manage_custom_fields.

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

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

Parâmetros

namestringcorpoobrigatório

The field's name, as the app shows it (up to 80 characters).

typeenumcorpoobrigatório

What the field holds; values are checked against it when records are written.

Valores: text, longtext, number, currency, currencyCode, country, date, datetime, daterange, select, multiselect, url, email, phone, checkbox, user, member, members, rating, progress, files

entityenumcorpoobrigatório

The kind of record the field belongs to.

Valores: deal, person, company, prospect, product

slugstringcorpoopcional

The key of the field in the records' customFields (lowercase letters, numbers and _); without it, it comes from the name. 409 custom_field_slug_taken if that entity already has it.

optionsarray<object>corpoopcional

For select and multiselect: the options (up to 100).

is_requiredbooleancorpoopcional

The app asks for it before saving the record.

default_valueanycorpoopcional

The value a new record starts with (up to 2 KB).

help_textstringcorpoopcional

A hint shown under the field (up to 300 characters).

group_namestringcorpoopcional

The section of the record where the field is shown.

show_in_tablebooleancorpoopcional

Shown as a column in the lists.

show_in_drawerbooleancorpoopcional

Shown in the record's side panel.

Resposta

field_idstring

Erros

crm_action_deniedinvalid_inputunknown_fieldauthentication_requiredscope_insufficientidempotency_key_reusedrate_limitedquota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/custom-fields" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "type": "text",
  "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 POST "https://api.mb-suite.com/v1/crm/custom-fields" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "type": "text",
  "entity": "deal"
}'
PATCH/v1/crm/custom-fields/{field_id}

Update a custom field

crm.custom_fields.update

EscritaDesde 2026-11-01

Updates the name, options, required flag, default value, help text, group, visibility or order of a custom field: send them at the top level or inside updates (not both: updates_conflict), at least one (no_changes otherwise). The slug and the type do not change (the stored values depend on them). Returns the field as saved and changed: false when it already was that way (nothing written). Requires manage_custom_fields.

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

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

Parâmetros

field_idstringrotaobrigatório

The field, by id (crm.custom_fields.list).

namestringcorpoopcional

The field's name, as the app shows it (up to 80 characters).

optionsarray<object>corpoopcional

For select and multiselect: the options (up to 100).

is_requiredbooleancorpoopcional

The app asks for it before saving the record.

default_valueanycorpoopcional

The value a new record starts with (up to 2 KB).

help_textstringcorpoopcional

A hint shown under the field (up to 300 characters).

group_namestringcorpoopcional

The section of the record where the field is shown.

show_in_tablebooleancorpoopcional

Shown as a column in the lists.

show_in_drawerbooleancorpoopcional

Shown in the record's side panel.

orderintegercorpoopcional

Its position among the fields 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 field already was that way: nothing was written.

fieldobject

Erros

custom_field_not_foundcrm_action_deniedinvalid_inputunknown_fieldauthentication_requiredscope_insufficientidempotency_key_reusedrate_limitedquota_exceeded

Exemplo

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

Delete a custom field definition

crm.custom_fields.delete

IrreversívelDesde 2026-11-01

Deletes the definition of a custom field; the values already stored in records are kept and simply stop being shown. The definition goes to the 30-day trash. Requires manage_custom_fields.

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 · Ação do CRM: manage_custom_fields
Tool do MCP
crm_custom_fields_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.custom_fields.delete".

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

Parâmetros

field_idstringrotaobrigatório

The field, by id (crm.custom_fields.list).

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

custom_field_not_founddelete_not_allowedconfirmation_requiredcrm_action_deniedinvalid_inputunknown_fieldauthentication_requiredscope_insufficientidempotency_key_reusedrate_limitedquota_exceeded

Exemplo

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