Skip to main content

Form endpoint

The Form endpoint accepts a multipart/form-data request made of named fields, each one typed and mapped to its own connector in your workflow. A single call can therefore carry text, numbers, JSON and files side by side.

Use it when a payload is not just one document: an upload accompanied by its metadata, an HTML form posted straight to Zparse, or any call where you would otherwise have to stuff several values into one JSON blob.

Pre-requisite​

Your workflow must be configured with a Form endpoint function node. You declare your fields there — key, type, and whether the field is mandatory — and each declared field becomes an output connector on the node.

Configuration​

See platform reference: How to configure the Form endpoint

Usage​

Call the given url from your own http client using a POST request, sending one form part per declared field.

Declared fields (form parts)required

One part per field declared on the node, named exactly as its key. A field declared Text is sent as-is, Integer must parse as a whole number, JSON must parse as valid JSON, and File is sent as a file part.

Authorization (header)

If private workflow: Configured access key. Cf: How to handle Authentication.

X-ZPARSE-IO-ATTR (header)

Optional header you can use to provide additional context to your call.

X-ZPARSE-IO-AUTH (header)

Optional header you can use to check extra security.


Example using Curl:
curl https://api.zparse.io/workflow/e/form/xxx/yyy \
  -H 'Authorization: {ACCESS_KEY}' \
  -XPOST \
  -F "invoice=@/path/to/invoice.pdf" \
  -F "customer_ref=ACME-42" \
  -F "priority=3" \
  -F 'options={"notify": true}'
Example in python:
def publish_form(file_path, secret_key):
    headers = {
        'Authorization': secret_key,
    }

    with open(file_path, 'rb') as file:
        files = {'invoice': (file_path, file, 'application/octet-stream')}
        data = {
            'customer_ref': 'ACME-42',
            'priority': '3',
            'options': '{"notify": true}',
        }
        return requests.post('https://api.zparse.io/workflow/e/form/xxx/yyy', files=files, data=data, headers=headers)

Field rules​

  • Unknown parts are ignored. A part whose name matches no declared field is read and discarded, so adding fields on your side never breaks the call.
  • A missing mandatory field fails the request. The run does not start.
  • A missing optional field falls back to its default when one is configured on the node, and is simply absent otherwise.
  • Type mismatches fail the request — a non-numeric value on an Integer field, or malformed JSON on a JSON field.

Response​

The Form endpoint always runs the workflow asynchronously and answers as soon as the run is accepted:

  • an authenticated call receives the execution tracker as JSON, which you can follow from Workflow Monitoring;
  • an anonymous call on a public endpoint receives an empty 200.

Getting the responder output​

A responder wired to a Form endpoint still runs — its payload is simply not returned inline in the POST response. Poll the tracker returned by your call and download the payload from the responder's step: the procedure is described in Retrieving a response.

Authentication required

The tracker route is authenticated, so this flow is only available to callers sending an access key. An anonymous call on a public Form endpoint receives an empty 200 and has no way to read the result back.