Submit Form

Submit answers to a published form from external systems

POST /public/forms/submitForm

Accepts form submissions from external applications and processes them through the same pipeline as the standard Zyntro form UI — contact creation or update, enrichment, CRM field mapping, and form action triggers. Answers are keyed by merge tag names (the `answer_key` values from Get Form Fields).

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
`org_id`	body	`string`	Yes	Your organization UUID
`member_id`	body	`string`	Yes	The member UUID performing the submission
`brand_id`	body	`string`	Yes	Your brand ID
`form_id`	body	`string`	Yes	The UUID of the form to submit to
`answers`	body	`object`	Yes	An object keyed by merge tag names (from `answer_key` in Get Form Fields). Values are the submitted answers. Example: `{"email": "[email protected]", "first_name": "Jane", "interest": "enterprise"}`
`ip_data`	body	`object`	Yes	Geolocation data for the submitter. Required sub-fields: `ip_address`, `city`, `country`, `country_code`, `timezone`, `lattitude`, `longitude`. If unavailable, pass empty strings — but all fields must be present.
`contact_id`	body	`string`	No	If you already know the contact UUID, pass it to link the submission to an existing contact instead of creating a new one.

Important: Answer keys must match the merge tag names from **Get Form Fields** (the `answer_key` values), not the internal field UUIDs. For example, use `"email"` not the UUID. If no answer keys match any form field, the submission is rejected. If some match and some do not, only the matched answers are processed — unmatched keys are silently ignored.

Request Body

Content-Type: application/json

Example

json

{
    "org_id": "YOUR_ORG_ID",
    "answers": {
        "email": "[email protected]",
        "message": "I would like to learn more about the enterprise plan.",
        "interest": "enterprise",
        "first_name": "Jane"
    },
    "api_key": "YOUR_API_KEY",
    "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "ip_data": {
        "city": "San Francisco",
        "country": "United States",
        "timezone": "America/Los_Angeles",
        "lattitude": "37.7749",
        "longitude": "-122.4194",
        "ip_address": "203.0.113.42",
        "country_code": "US"
    },
    "brand_id": "1",
    "member_id": "YOUR_MEMBER_ID"
}

Code Samples

bash

curl -X POST https://app.zyntrohq.com/public/forms/submitForm \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "org_id": "YOUR_ORG_ID",
    "member_id": "YOUR_MEMBER_ID",
    "brand_id": "1",
    "form_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "answers": {
      "first_name": "Jane",
      "email": "[email protected]",
      "interest": "enterprise"
    },
    "ip_data": {
      "ip_address": "203.0.113.42",
      "city": "San Francisco",
      "country": "United States",
      "country_code": "US",
      "timezone": "America/Los_Angeles",
      "lattitude": "37.7749",
      "longitude": "-122.4194"
    }
  }'

Info: On successful submission, a `completion_id` is returned. If your form has a `redirect_url` configured in its form actions, the `completion_id` is appended as a query parameter to that URL along with any other configured params. Use the **Get Form Completion** endpoint to retrieve the full submission record, including the `contact_id` once contact enrichment completes.

Response

200 Form submitted successfully

json

{
    "data": {
        "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "completion_id": "c9d8e7f6-a5b4-3210-fedc-ba9876543210"
    },
    "status": "success"
}

200 Error — no answer keys matched

json

{
    "data": [
        "None of the provided answer keys matched any form field merge tags. Unmatched keys: company, role"
    ],
    "status": "error"
}

Warning: The `ip_data` object uses `lattitude` (with a double 't') as the field name. This is an intentional API convention — do not correct it to `latitude` or the field will be treated as missing.

Errors

Code	Message	Resolution
`MISSING_FIELD`	Missing required field: {field} A required parameter is missing.	Include all required fields including ip_data sub-fields.
`MISSING_IP_FIELD`	Missing ip_data field: {field} A required ip_data sub-field is missing.	Include all 7 ip_data fields. Pass empty strings if data is unavailable.
`INVALID_API_KEY`	Invalid API Key No active user matches the key.	Verify your key.
`FORM_NOT_FOUND`	Form not found No form with that ID exists.	Verify the form_id.
`NOT_PUBLISHED`	Form is not published. Only published forms accept submissions. The form exists but is not published.	Publish the form first.
`NO_MATCH`	None of the provided answer keys matched any form field merge tags. Every answer key you sent is unrecognized.	Use Get Form Fields to discover the correct answer_key values.
`PROCESSING_ERROR`	Internal processing error The form processor failed.	Check the error details and retry.

5 min read Updated Apr 2, 2026

Navigation

Submit Form

Parameters

Request Body

Example

Code Samples

Response

Errors