Referência da API · Web Forms

Respostas

web_forms · submissions · 6 operações

GET/v1/web-forms/{form_id}/submissionsList the responses of a web form GET/v1/web-forms/{form_id}/submissions/{submission_id}Get one response of a web form DELETE/v1/web-forms/{form_id}/submissions/{submission_id}Delete one response of a web form POST/v1/web-forms/{form_id}/submissions/bulk/deleteDelete many responses of a web form POST/v1/web-forms/{form_id}/submissions/{submission_id}/resend-notificationRe-send the notification email of a response POST/v1/web-forms/{form_id}/submissions/{submission_id}/record-testRecord a test of the form made through the public endpoint

GET/v1/web-forms/{form_id}/submissions

List the responses of a web form

web_forms.submissions.list

LeituraIdempotenteDesde 2026-11-01

Lists the responses a web form received, newest first, paginated by cursor (limit up to 200). Without status it returns the real responses (success, and email_failed: stored but the notification email failed); status=rejected returns what the spam filters dropped (stored without its values), status=all everything. since (epoch ms) keeps only responses received at or after that time, for incremental syncs. Each response carries payload (field name → value, exactly as submitted), the notification result, the CRM lead it created (lead_id, lead_type, person_id) and the ad attribution captured by the MB Suite pixel; the browser (user_agent) comes with web_forms.submissions.get. The visitor's IP is never stored in clear and its hash is not returned. Not found if the form does not exist. Requires view access to Web Forms.

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

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

limitintegerqueryopcional

How many items this page brings at most (see the maximum and the default in the schema).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

statusenumqueryopcional

Omit for the real responses (success and email_failed); 'rejected' for what the spam filters dropped; 'all' for everything.

Valores: success, email_failed, rejected, all

sinceintegerqueryopcional

Only responses received at or after this time (epoch milliseconds).

Resposta

dataarray<object>

has_moreboolean

next_cursorstring

Erros

web_form_not_found 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/web-forms/{form_id}/submissions" \
  -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}/submissions" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/web-forms/{form_id}/submissions/{submission_id}

Get one response of a web form

web_forms.submissions.get

LeituraIdempotenteDesde 2026-11-01

Returns one response of a web form: payload (field name → value), when and from which origin it arrived, its status (success, email_failed or rejected with rejection_reason), who got the notification email (notification_recipients, notification_routed_value), the auto-responder result, the CRM lead it created and its ad attribution. Not found (web_form_submission_not_found) if the response does not exist in that form. Requires view access to Web Forms.

Escopo: web_forms:read
Permissão: Ver o módulo
Tool do MCP: web_forms_submissions_getNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.submissions.get".

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

submission_idstringrotaobrigatório

The response's id (from web_forms.submissions.list).

Resposta

idstring

form_idstring

received_atnumber

originstring

payloadobject

statusenum

Valores: success, email_failed, rejected

email_sentboolean

lead_createdboolean

user_agentstring

rejection_reasonstring | null

email_message_idstring | null

email_errorstring | null

notification_recipientsarray<string>

notification_routed_valuestring | null

auto_responder_sentboolean

auto_responder_errorstring | null

auto_responder_skip_reasonstring | null

lead_idstring | null

lead_typeenum | null

Valores: deal, prospect

person_idstring | null

attributionobject | null

recaptcha_scorenumber

recaptcha_outcomestring

tested_byobject

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/web-forms/{form_id}/submissions/{submission_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}/submissions/{submission_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

DELETE/v1/web-forms/{form_id}/submissions/{submission_id}

Delete one response of a web form

web_forms.submissions.delete

IrreversívelDesde 2026-11-01

Deletes one response of a web form for good and rolls back the form's counters (for example, to honor a data deletion request). It does NOT go to the trash and cannot be undone; the notification email already sent and any CRM lead it created are not touched (delete the lead in the CRM if needed). Outside the screen it requires a dry run and a confirm_token. Requires edit access to Web Forms and, for a credential, deletion enabled.

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_submissions_deleteNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.submissions.delete".

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

submission_idstringrotaobrigatório

The response's id (from web_forms.submissions.list).

Resposta

oktrue

Erros

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

POST/v1/web-forms/{form_id}/submissions/bulk/delete

Delete many responses of a web form

web_forms.submissions.bulk.delete

IrreversívelEm massa · até 500Desde 2026-11-01

Deletes up to 500 responses of one web form for good (ids that do not exist are skipped) and rolls back the form's counters. They do NOT go to the trash and cannot be undone; notification emails already sent and CRM leads already created are not touched. Outside the screen it requires a dry run (which counts what exists) and a confirm_token. Returns how many were deleted. Requires edit access to Web Forms and, for a credential, deletion enabled.

Escopo: web_forms:write e «Permitir exclusões» (web_forms:delete no OAuth)
Permissão: Editar no módulo
Tool do MCP: web_forms_submissions_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.submissions.bulk.delete".

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

submission_idsarray<string>corpoobrigatório

The responses' ids (1 to 500), from web_forms.submissions.list.

Resposta

deletednumber

Erros

web_form_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 POST "https://api.mb-suite.com/v1/web-forms/{form_id}/submissions/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "submission_ids": [
    "SUBMISSION_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/web-forms/{form_id}/submissions/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "submission_ids": [
    "SUBMISSION_ID"
  ],
  "dry_run": true
}'

POST/v1/web-forms/{form_id}/submissions/{submission_id}/resend-notification

Re-send the notification email of a response

web_forms.submissions.resend_notification

EscritaDesde 2026-11-01

Sends the notification email of one response again, with the form's current recipients and routing, through Amazon SES (for example after fixing to_emails when the first send failed). Updates the response's email status: a successful re-send marks an email_failed response as success. A rejected response cannot be re-sent (web_form_submission_rejected: it was stored without its values). Returns sent=false with the error instead of failing. Sends a real email. 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.

Escopo: web_forms:write
Permissão: Editar no módulo
Tool do MCP: web_forms_submissions_resend_notificationNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.submissions.resend_notification".

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

submission_idstringrotaobrigatório

The response's id (from web_forms.submissions.list).

Resposta

sentboolean

message_idstring | null

errorstring | null

recipientsarray<string>

Erros

web_form_not_found confirmation_required external_rejected external_unavailable external_rate_limited external_outcome_unknown sandbox_external_unavailable 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/web-forms/{form_id}/submissions/{submission_id}/resend-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.

POST/v1/web-forms/{form_id}/submissions/{submission_id}/record-test

Record a test of the form made through the public endpoint

web_forms.submissions.record_test

EscritaIdempotenteDesde 2026-11-01

Records in the audit log a test of the form made through the public endpoint (POST https://mb-suite.com/api/v1/public/forms/submit from one of the form's allowed origins, which goes through the origin check, the rate limits, the honeypot and the CAPTCHA like any visitor) and marks the response with tested_by. Send the submission_id the endpoint returned (it returns one only when the response came in). The response must be of that form, must have come in through the endpoint (a test from the editor or web_forms.forms.test_submit, origin __test__, gives 409 web_form_submission_is_test; a rejected one, 409 web_form_submission_rejected) and must have been received in the last 15 minutes (409 web_form_submission_too_old). note (optional, one line) says what was tested. The audit entry (web_forms.test_submit) is under the person behind the credential, with submittedVia public_endpoint, the response's origin, whether the notification email went out (email_sent) and whether a CRM lead was created (lead_created). Recording the same response again changes nothing (changed false) and does not audit again. It sends nothing and creates nothing. 404 web_form_not_found or web_form_submission_not_found. Requires edit access to Web Forms.

Escopo: web_forms:write
Permissão: Editar no módulo
Tool do MCP: web_forms_submissions_record_testNa superfície completa; na compacta, mb_execute_operation com id: "web_forms.submissions.record_test".

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

Parâmetros

form_idstringrotaobrigatório

The form's id (from web_forms.forms.list, or the form_id that web_forms.forms.create returns).

submission_idstringrotaobrigatório

The response's id (from web_forms.submissions.list).

notestringcorpoopcional

What the test checked, in one line (up to 500 characters): it is stored on the response and in the audit entry.

Resposta

form_idstring

submission_idstring

changedboolean

originstring

received_atnumber

email_sentboolean

lead_createdboolean

tested_byobject

Erros

web_form_not_found 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/web-forms/{form_id}/submissions/{submission_id}/record-test" \
  -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}/submissions/{submission_id}/record-test" \
  -H "Authorization: Bearer $MB_TEST_KEY"