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