Formulários

List web forms

web_forms.forms.list

Lists the organization's web forms (HTML forms embedded on websites that email every submission and can feed the CRM), newest first, paginated by cursor (limit up to 200). enabled=true returns only published forms (accepting submissions), false only unpublished ones; the page is completed up to limit (reading up to 500 forms per call). Each row carries the notification recipients, allowed origins, anti-spam settings, CRM link, counters, created_by_name, field_count and auto_responder_enabled; the fields and the auto-responder come with web_forms.forms.get. Use web_forms.submissions.list for the responses. Requires view access to Web Forms.

Escopo

web_forms:read

Permissão

Ver o módulo

Tool do MCP

web_forms_forms_listNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.list".

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

Parâmetros

Resposta

Erros

Exemplo

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

Get one web form

web_forms.forms.get

Returns one web form: its fields (name, label, type, required, crm_template), the notification email (from_name, to_emails, subject, conditional recipient_routing), allowed_origins, the anti-spam settings (honeypot_field_name, recaptcha_enabled, rate_limits), thank_you_url, the auto-responder, the CRM link (linked_source_id), its counters (stats) and who created it (created_by_id, created_by_name). A visitor's page submits with POST https://mb-suite.com/api/v1/public/forms/submit?formId=<id> and a JSON body {"formId": <id>, "<field name>": <value>, …}, sent from one of allowed_origins. Not found (web_form_not_found) if the id does not exist in this organization. Requires view access to Web Forms.

Escopo

web_forms:read

Permissão

Ver o módulo

Tool do MCP

web_forms_forms_getNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.get".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/web-forms/{form_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 "https://api.mb-suite.com/v1/web-forms/{form_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a web form

web_forms.forms.create

Creates a web form: name, 1 to 40 fields (name, label, type text|email|phone|textarea|number, required), the internal recipients of the notification email (to_emails, up to 10), its sender name and subject ({{field_name}} placeholders allowed), the origins allowed to submit (allowed_origins, scheme://host without path) and optionally a thank-you URL, conditional routing of recipients, an auto-responder (needs a verified Branding domain and sender), rate limits and CRM availability. It is created unpublished by default (enabled=false): publish it with web_forms.forms.publish (or create it with enabled=true) and from then on it accepts submissions at POST https://mb-suite.com/api/v1/public/forms/submit and emails each one to to_emails. reCAPTCHA is off by default through the API; turn it on only if the page sends a g-recaptcha-response token. The CRM link is made from the CRM (a lead source of type MB Suite Form) or with web_forms.forms.link_crm, which can also create that source (create_source). Errors: branding_not_verified / sender_not_found (a sender_id or auto-responder sender not usable), routing_field_reserved. Returns the new form_id and the form. Requires edit access to Web Forms.

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_createNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.create".

Eventos que pode emitir

web_forms.form.published

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "fields": [],
  "from_name": "FROM_NAME",
  "to_emails": [
    "ana@example.com"
  ],
  "subject": "SUBJECT",
  "allowed_origins": [
    "ALLOWED_ORIGIN"
  ]
}'

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/web-forms" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "fields": [],
  "from_name": "FROM_NAME",
  "to_emails": [
    "ana@example.com"
  ],
  "subject": "SUBJECT",
  "allowed_origins": [
    "ALLOWED_ORIGIN"
  ]
}'

Update a web form

web_forms.forms.update

Updates one or more settings of a web form (updates object): name, description, enabled, fields, honeypot_field_name, from_name, sender_id, to_emails, subject, reply_to_field, recipient_routing (null removes it), allowed_origins, recaptcha_enabled, recaptcha_min_score (null = global default), thank_you_url (null removes it), rate_limits, auto_responder, email_branding, crm_enabled. Only what is sent changes; fields replaces the whole list. crm_enabled cannot be turned off while the form is linked to a CRM lead source (crm_enabled_required_while_linked: unlink it first with web_forms.forms.unlink_crm). To only publish or unpublish prefer web_forms.forms.publish / unpublish. Returns the updated form. Requires edit access to Web Forms.

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_updateNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.update".

Eventos que pode emitir

web_forms.form.published

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

Parâmetros

Resposta

Erros

Exemplo

curl -X PATCH "https://api.mb-suite.com/v1/web-forms/{form_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

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/web-forms/{form_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Publish a web form

web_forms.forms.publish

Publishes a web form (enabled=true): from now on the public endpoint accepts its submissions, emails them and, when linked, sends them to the CRM. Idempotent: on a form that is already published nothing changes (changed=false). Returns the form. Requires edit access to Web Forms.

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_publishNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.publish".

Eventos que pode emitir

web_forms.form.published

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/publish" \
  -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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/publish" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Unpublish a web form

web_forms.forms.unpublish

Unpublishes a web form (enabled=false): the public endpoint answers its submissions with a generic 404 and stores nothing, while the form, its responses and its CRM link are kept. Use it to pause a form instead of deleting it. Idempotent: on a form that is already unpublished nothing changes (changed=false). Requires edit access to Web Forms.

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_unpublishNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.unpublish".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/unpublish" \
  -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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/unpublish" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Duplicate a web form

web_forms.forms.duplicate

Copies a web form with all its settings into a new one named '<name> (copy)' (the suffix in the caller's language: '(copia)', '(copy)' or '(cópia)'), unpublished, without the CRM link (a lead source points to a single form) and with its counters at zero; responses are not copied. Returns the new form_id and the form. Requires edit access to Web Forms.

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_duplicateNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.duplicate".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/duplicate" \
  -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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/duplicate" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a web form and its responses

web_forms.forms.delete

Deletes a web form together with ALL its responses, and removes its link with the CRM lead source (the source stays active; leads already created stay in the CRM). The form's configuration goes to the 30-day trash and owners and admins can restore it (it comes back unlinked from the CRM and with its counters at zero); the responses are deleted for good and do not come back: export them first with web_forms.submissions.list if they are needed. To pause a form use web_forms.forms.unpublish instead. Outside the screen it always requires a dry run (which says how many responses will be lost) and a confirm_token. Requires edit access to Web Forms.

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

web_forms:write e «Permitir exclusões» (web_forms:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_deleteNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.delete".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/web-forms/{form_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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 DELETE "https://api.mb-suite.com/v1/web-forms/{form_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Send a test notification email

web_forms.forms.send_test_notification

Sends the form's notification email with dummy values to its configured recipients (to_emails, or the routing defaults), through Amazon SES, so the recipients and the look of the email can be checked. Stores nothing. Returns sent=false with the error (for example, no valid recipients) instead of failing; the attempt is audited either way. At most one test per form and person every 30 seconds (cooldown_active, 429). Sends a real email: run it only when the person asks to test the notification. Outside the app it always runs in two steps: dry_run=true says to whom it goes (and, for a test submission, whether it creates a CRM lead and where the auto-reply goes) with the same checks and a confirm_token (10 minutes); then call it again with the confirm_token. Requires edit access to Web Forms.

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

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_send_test_notificationNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.send_test_notification".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ses): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/test-notification" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Send a test submission through the whole pipeline

web_forms.forms.test_submit

Runs a test submission of the form with the given values ({name, value} pairs, one per field) through the real pipeline, skipping only the origin, rate-limit, honeypot and CAPTCHA checks: it validates the values against the form's fields (validation_failed with details.fields), stores a response marked as a test (origin __test__), sends the notification email to the form's recipients through Amazon SES, creates a REAL lead in the CRM when the form is linked to a lead source, and sends the auto-responder (if on) to the caller's own email with a [TEST] subject prefix. It does not fire web_forms.submission.received. At most one test per form and person every 30 seconds (cooldown_active). Returns what happened at each step. Run it only when the person asks to test the form. Outside the app it always runs in two steps: dry_run=true says to whom it goes (and, for a test submission, whether it creates a CRM lead and where the auto-reply goes) with the same checks and a confirm_token (10 minutes); then call it again with the confirm_token. Requires edit access to Web Forms.

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

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_test_submitNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.test_submit".

Eventos que pode emitir

crm.lead.createdcrm.deal.created

Custo declarado: até 3 leituras e 4 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ses): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/test-submit" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "values": [],
  "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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Link a web form to a CRM lead source, or create the source for it

web_forms.forms.link_crm

Takes a web form to the CRM: from then on every real submission also creates a lead in the CRM with the source's destination, pipeline, field mapping and deduplication, and the form is marked available to the CRM (crm_enabled). Two ways, one per call. With source_id: links an existing lead source of type mb_suite_form that is free (crm.lead_sources.list with type mb_suite_form); both sides are written in one transaction and the source is reactivated. With create_source: true: creates a new lead source of type mb_suite_form for this form and links it in the same transaction, as CRM → Settings → Sources → MB Suite Form does; new_source sets its name (default: the form's), destination (prospect by default, or deal), pipeline and stage (validated: a deal source needs its pipeline; without a stage, its first one) and deduplication (merge by default). Every field of the form is mapped to the CRM (email, phone, name, company, website and the like to their CRM fields, the rest to custom:<field name>, so no answer is lost); labels and AI scoring are left out (AI scoring costs AI credits per lead, so it starts off): change them with crm.lead_sources.update. Creating a source needs manage_sources in the CRM (CRM admins, owners and admins). The dry run (dry_run: true) runs the same checks without writing and says what it would create or link. Errors: lead_source_not_found, lead_source_type_invalid, web_form_already_linked (the form already has a source: unlink it first with web_forms.forms.unlink_crm; its source is in details.source_id), lead_source_already_linked, and the pipeline and stage ones (pipeline_required, pipeline_not_found, pipeline_archived, stage_not_in_pipeline). Linking the source it already has changes nothing (changed false); with create_source, a second call finds the form linked (web_form_already_linked) and never creates another source. It fires no webhook event: the leads the form creates later fire crm.lead.created or crm.deal.created. Returns form_id, the source_id linked (the new one with create_source) and changed. Writes in the CRM: requires edit access to Web Forms AND to the CRM (and the crm:write scope for a credential).

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_link_crmNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.link_crm".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/crm-link" \
  -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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/crm-link" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Unlink a web form from its CRM lead source

web_forms.forms.unlink_crm

Removes the link between the form and its CRM lead source (both sides, in one transaction): new submissions stop creating CRM leads, while the source keeps its history and stays as it was (active or not), and leads already created are kept. Idempotent: a form without a link returns unlinked_source_id=null. Writes in the CRM: requires edit access to Web Forms AND to the CRM (and the crm:write scope for a credential).

Escopo

web_forms:write

Permissão

Editar no módulo

Tool do MCP

web_forms_forms_unlink_crmNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.forms.unlink_crm".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/web-forms/{form_id}/crm-unlink" \
  -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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/crm-unlink" \
  -H "Authorization: Bearer $MB_TEST_KEY"