Forms
| Tool | What it does |
|---|---|
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. |
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. |
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. |
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. |
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. |
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. |
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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-analytics-summary |
| MCP tool | form_analytics_summary on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_oid | string | Yes | The 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-contact-submissions |
| MCP tool | form_contact_submissions on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_oid | string | Yes | The form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$. |
contact_oid | string | Yes | The contact’s id: 24 lowercase hex characters, from the form’s contact list. Pattern ^[a-f0-9]{24}$. |
page | integer | No | Page 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-create-draft |
| MCP tool | form_create_draft on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create & edit forms (forms.create_edit) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The form’s internal name, up to 120 characters. It also seeds the form’s link name. Length 1 to 120. |
template | string (enum) | No | DEMO_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_fields | array of object | No | Extra questions to add after the template’s fields, at most 15. Leave empty to add none. Up to 15 items. |
button_text | string | No | The 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-get |
| MCP tool | form_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_oid | string | Yes | The 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-list |
| MCP tool | form_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, starting at 1, 25 forms per page. From 1 to 100000. Default 1. |
status | string (enum) | No | Only forms in this status: DRAFT (never published), LIVE, or OFF (published, switched off). Ignored when archived is true. One of: DRAFT, LIVE, OFF. |
type | string (enum) | No | Only built forms (hosted or embedded) or connected forms (the team’s own site form, filled in by Prospeo). One of: BUILT, CONNECTED. |
search | string | No | Part of the form’s name, up to 120 characters. Length 1 to 120. |
archived | boolean | No | True 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/form-submissions-list |
| MCP tool | form_submissions_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
form_oid | string | Yes | The form’s id: 24 lowercase hex characters, from the form list. Pattern ^[a-f0-9]{24}$. |
page | integer | No | Page number, starting at 1, 25 contacts per page. From 1 to 100000. Default 1. |
search | string | No | Match a contact’s name, their company’s name, or an exact email address, up to 120 characters. Length 1 to 120. |
sort | string (enum) | No | Order by latest submission: newest first (default) or oldest first. One of: newest, oldest. Default "newest". |
submitted_after | string | No | Only contacts whose latest submission is at or after this timestamp (ISO 8601). |
submitted_before | string | No | Only contacts whose latest submission is at or before this timestamp (ISO 8601). |
unassigned | boolean | No | True to also include contacts nobody owns yet, alongside any owner_user_oids. Default false. |
owner_user_oids | array of string | No | Only contacts owned by these teammates (their user ids), at most 20. Up to 20 items. |
sources | array of string | No | Only 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. |
answers | array of object | No | Only 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.