Skip to Content

Forms

ToolWhat it does
form_analytics_summarySay whether one form’s Analytics tab has data yet, with its total views and submissions. Reports totals only, not trends, sources or field drop-off.
form_contact_submissionsShow one contact’s submission history on one form: when, repeats, source, and their answers to choice, number, yes-or-no and consent questions. Personal answers such as name, email, phone and free text are not shown.
form_create_draftCreate a new DRAFT form from a template, optionally adding a few simple questions. Needs approval. Nothing is published or switched on, so tell the user it is only a draft and that they finish and publish it in Forms.
form_getShow one form: name, status, type, link, fields, what happens after a submit, owner, connection health for connected forms, what blocks publishing it, and submission totals.
form_listList the team’s forms with status (draft, live, off or archived), type (built or connected), views, submissions, conversion and owner. Filter by status, type, name or the archived group; 25 per page.
form_submissions_listList the contacts who submitted one form, newest first: name, company, owner, how many times they submitted and where they came from. Never includes their answers or email addresses.

form_analytics_summary

Say whether one form’s Analytics tab has data yet, with its total views and submissions. Reports totals only, not trends, sources or field drop-off.

Say whether one form’s Analytics tab has data yet - nothing recorded, still catching up, or ready - with the form’s total views and submissions and its latest submission date. Reports totals only; it does not break results down by source, field or time, and says so.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-analytics-summary
MCP toolform_analytics_summary on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
form_oidstringYesThe form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

form_contact_submissions

Show one contact’s submission history on one form: when, repeats, source, and their answers to choice, number, yes-or-no and consent questions. Personal answers such as name, email, phone and free text are not shown.

Show one contact’s submission history on one form, newest first: when each submission happened, whether it was a repeat, where it came from, and the contact’s answers to choice, number, yes-or-no and consent questions. Personal answers (email, phone, name, location, free text, hidden fields, company, job title) are listed by question with their values withheld, and the result says how many were kept out.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-contact-submissions
MCP toolform_contact_submissions on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
form_oidstringYesThe form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$.
contact_oidstringYesThe contact’s id: 24 lowercase hex characters, from the form’s contact list. Pattern ^[a-f0-9]{24}$.
pageintegerNoPage number, starting at 1, 25 submissions per page. From 1 to 100000. Default 1.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

form_create_draft

Create a new DRAFT form from a template, optionally adding a few simple questions. Needs approval. Nothing is published or switched on, so tell the user it is only a draft and that they finish and publish it in Forms.

Create a new DRAFT form for the user from a template (Demo request, Contact us, Lead magnet or blank), optionally adding up to 15 simple questions and a custom submit button text. Always asks for approval first. Nothing is published, switched on or shared: the form is created as a draft owned by the user, with an automatic link name, and the user opens Forms to finish the design and publish it.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-create-draft
MCP toolform_create_draft on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate & edit forms (forms.create_edit)
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
namestringYesThe form’s internal name, up to 120 characters. It also seeds the form’s link name. Length 1 to 120.
templatestring (enum)NoDEMO_REQUEST (email, name, company, phone, what to discuss, consent), CONTACT_US (email, name, message), LEAD_MAGNET (email only, goes to a URL after submit) or BLANK. Omit for a blank form with just the email field. One of: DEMO_REQUEST, CONTACT_US, LEAD_MAGNET, BLANK.
extra_fieldsarray of objectNoExtra questions to add after the template’s fields, at most 15. Leave empty to add none. Up to 15 items.
button_textstringNoThe submit button’s text, up to 60 characters. Omit to keep the template’s own. Length 1 to 60.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

form_get

Show one form: name, status, type, link, fields, what happens after a submit, owner, connection health for connected forms, what blocks publishing it, and submission totals.

Show one form: its name, status (draft, live, off or archived), type (built in Prospeo or connected to the team’s own site form), public link once published, the questions on it, what the visitor sees after a submit, the owner, connection health for connected forms, what blocks publishing it, whether it has unpublished edits, and its view and submission totals.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-get
MCP toolform_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
form_oidstringYesThe form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

form_list

List the team’s forms with status (draft, live, off or archived), type (built or connected), views, submissions, conversion and owner. Filter by status, type, name or the archived group; 25 per page.

List the team’s forms, most recently updated first, 25 per page: name, type (built or connected), status (draft, live, off), views, submissions, conversion, latest submission, owner and connection health, with the count of archived forms. Filter by status, type, part of the name, or switch to the archived group.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-list
MCP toolform_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
pageintegerNoPage number, starting at 1, 25 forms per page. From 1 to 100000. Default 1.
statusstring (enum)NoOnly forms in this status: DRAFT (never published), LIVE, or OFF (published, switched off). Ignored when archived is true. One of: DRAFT, LIVE, OFF.
typestring (enum)NoOnly built forms (hosted or embedded) or connected forms (the team’s own site form, filled in by Prospeo). One of: BUILT, CONNECTED.
searchstringNoPart of the form’s name, up to 120 characters. Length 1 to 120.
archivedbooleanNoTrue to list the archived group instead of the active forms. Default false.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

form_submissions_list

List the contacts who submitted one form, newest first: name, company, owner, how many times they submitted and where they came from. Never includes their answers or email addresses.

List the contacts who submitted one form, 25 per page, newest submission first: name, company, owner, how many times they submitted, latest and first submission dates, and where they came from, with a link to each contact. Filter by name, company or exact email search, date range, owner or unassigned. Never includes their answers, their email addresses or their enrichment columns.

EndpointPOST https://api.prospeo.io/api/v2/tools/form-submissions-list
MCP toolform_submissions_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
form_oidstringYesThe form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$.
pageintegerNoPage number, starting at 1, 25 contacts per page. From 1 to 100000. Default 1.
searchstringNoMatch a contact’s name, their company’s name, or an exact email address, up to 120 characters. Length 1 to 120.
sortstring (enum)NoOrder by latest submission: newest first (default) or oldest first. One of: newest, oldest. Default "newest".
submitted_afterstringNoOnly contacts whose latest submission is at or after this timestamp (ISO 8601).
submitted_beforestringNoOnly contacts whose latest submission is at or before this timestamp (ISO 8601).
unassignedbooleanNoTrue to also include contacts nobody owns yet, alongside any owner_user_oids. Default false.
owner_user_oidsarray of stringNoOnly contacts owned by these teammates (their user ids), at most 20. Up to 20 items.
sourcesarray of stringNoOnly contacts whose latest submission came from one of these sources, as a contact’s source reads (for example Direct), at most 50. Up to 50 items.
answersarray of objectNoOnly contacts whose latest answer to each listed choice or yes-or-no question is one of its values, at most 10 questions. Up to 10 items.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

Last updated on