Collect Form Data (MCP)

A two-phase endpoint for AI agents to retrieve form fields and submit answers

POST /public/forms/collectFormData

A wrapper endpoint designed for AI agent consumption (MCP tools, Phona voice AI, LLM integrations). Operates in two phases: Phase 1 (get_fields) retrieves a simplified field schema optimized for LLM processing. Phase 2 (submit) sends collected answers through the standard form submission pipeline. Base identifiers (api_key, org_id, member_id, brand_id) are typically auto-injected by the MCP context.

Requires a valid `api_key` in the JSON request body

Parameters

Name	In	Type	Required	Description
`api_key`	body	`string`	Yes	Your Zyntro API key (auto-injected in MCP context)
`phase`	body	`string`	Yes	The operation phase: `get_fields` (retrieve field schema) or `submit` (send answers)
`form_id`	body	`string`	Yes	The UUID of the form
`org_id`	body	`string`	No	Your organization UUID (auto-injected in MCP context)
`member_id`	body	`string`	No	The member UUID (auto-injected in MCP context)
`brand_id`	body	`string`	No	Your brand ID (auto-injected in MCP context)
`answers`	body	`object`	No	Required for `phase: submit`. An object of collected answers keyed by field keys from the get_fields response.
`contact_id`	body	`string`	No	Optional for `phase: submit`. Link the submission to an existing contact.

Info: This endpoint is optimized for AI agent workflows — particularly Phona voice calls where the AI needs to ask form questions during a live conversation. Phase 1 returns a simplified field schema with an `instructions` field that tells the AI agent what to do next. Phase 2 handles submission with stubbed IP data (since the AI agent context has no real IP).

Request Body

Content-Type: application/json

Schema

json

{
    "phase_1": "get_fields \u2014 retrieve simplified field definitions",
    "phase_2": "submit \u2014 send collected answers"
}

Example

json

{
    "phase": "get_fields",
    "api_key": "YOUR_API_KEY",
    "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Code Samples

bash

curl -X POST https://app.zyntrohq.com/public/forms/collectFormData \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "phase": "get_fields",
    "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
  }'

bash

curl -X POST https://app.zyntrohq.com/public/forms/collectFormData \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "phase": "submit",
    "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "answers": {
      "first_name": "Jane",
      "email": "[email protected]",
      "interest": "enterprise"
    }
  }'

Response

200 Phase 1 — Fields retrieved

json

{
    "data": {
        "phase": "get_fields",
        "fields": [
            {
                "key": "first_name",
                "type": "textField",
                "label": "First Name",
                "required": true,
                "placeholder": "Enter your first name"
            },
            {
                "key": "email",
                "type": "emailField",
                "label": "Email Address",
                "required": true
            },
            {
                "key": "interest",
                "type": "dropdownField",
                "label": "What are you interested in?",
                "options": [
                    {
                        "label": "Enterprise Plan",
                        "value": "enterprise"
                    },
                    {
                        "label": "Starter Plan",
                        "value": "starter"
                    }
                ],
                "required": false
            }
        ],
        "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "form_name": "Contact Us",
        "instructions": "Collect answers for each field from the caller. Use the key as the answer identifier. Once all required fields are collected, call phase submit with the answers object."
    },
    "status": "success"
}

200 Phase 2 — Submission successful

json

{
    "data": {
        "phase": "submit",
        "message": "Form submitted successfully. Contact record updated.",
        "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "completion_id": "c9d8e7f6-a5b4-3210-fedc-ba9876543210"
    },
    "status": "success"
}

Tip: The Phase 1 response includes an `instructions` field — a natural-language prompt designed for AI agents. It tells the agent to collect answers for each field and then call Phase 2. If you are building a custom MCP tool, you can pass this instruction directly to your LLM to guide the data collection conversation.

Errors

Code	Message	Resolution
`MISSING_PHASE`	phase is required (get_fields or submit) The phase parameter is missing or invalid.	Set phase to `get_fields` or `submit`.
`MISSING_FORM_ID`	form_id is required The form_id is missing.	Provide the form UUID.
`MISSING_ANSWERS`	answers object is required Phase is submit but no answers were provided.	Include a non-empty answers object.
`INVALID_API_KEY`	Invalid API Key No active user matches the key.	Verify your key.
`INTERNAL_ERROR`	Internal request failed: ... The internal call to getFormFields or submitForm failed.	Check the error details — usually a form or auth issue.

5 min read Updated Apr 2, 2026

Navigation

Collect Form Data (MCP)

Parameters

Request Body

Schema

Example

Code Samples

Response

Errors