Web Forms: capture script and submissions endpoint

Every submission lands here, whether it comes from the capture script embedded on your site or from a request you build yourself, and the token in the URL is the only thing that authenticates it.

Where

Web Forms→Install

Your role needs

Read access to Web form capture endpoint read-web-forms. Admin, Member and Viewer have it by default.

To create

create-web-forms on top of the permission above.

Endpoint

Method	Path	Purpose
`POST`	`/api/public/web-forms/{token}/submissions`	Create one submission
`OPTIONS`	`/api/public/web-forms/{token}/submissions`	CORS preflight for the route above
`POST`	`/api/public/web-forms/{token}/forms`	Report the forms the capture script found on a page
`OPTIONS`	`/api/public/web-forms/{token}/forms`	CORS preflight for the route above

They live at https://api.pipelime.ai. {token} is the one credential they check. There’s no API key and no Authorization header, so treat the URL itself as the secret. The capture script uses both paths. A direct integration (your own code, a Zapier zap, a platform’s native webhook) only ever needs the submissions route. See Install methods: JavaScript snippet or direct endpoint for the script tag itself and the platform-specific guides.

Request body

Field	Type	Rule
`fields`	object	Required. Your own form field names as keys; each value must be a plain string, number, boolean, or `null`
`form_key`	string	Optional. Names one of the form definitions this form already holds under that key
`context`	object	Optional. Page and campaign metadata, listed below
`_hp`	string	Optional. A honeypot: see Honeypot and deduplication

A checkbox group or a multi-select has to arrive as one value, not an array: join the selected options into a single string before you send them. A fields value that’s an array or an object instead of a scalar, a field name that’s too long, or a value that’s too long all fail validation the same way; see Responses. A form_key is matched on the key alone. Nothing else about the definition is looked at. Send one that doesn’t match anything, or leave it out entirely, and the submission is queued exactly the same way; what decides whether it becomes a lead automatically, or waits in the product for you to map it, is on Field mapping and the submissions inbox. Every context key is an optional string, and only the keys below are read. Anything else you put in context is accepted and then ignored:

`context` key	Stored as
`page_url`	The submission’s own `page_url`
`referrer`	The submission’s own `referrer`
`page_title`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `fbclid`, `submitted_at`	Together, as the submission’s attribution data: only the keys you send with a non-empty value are kept

curl -X POST 'https://api.pipelime.ai/api/public/web-forms/YOUR_FORM_TOKEN/submissions' \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": {
      "name": "Jane Doe",
      "email": "jane.doe@acme-demo.test",
      "message": "Interested in a demo"
    },
    "context": {
      "page_url": "https://acme-demo.test/contact",
      "utm_source": "linkedin"
    }
  }'

{
  "fields": {
    "name": "Jane Doe",
    "email": "jane.doe@acme-demo.test",
    "message": "Interested in a demo"
  },
  "context": {
    "page_url": "https://acme-demo.test/contact",
    "utm_source": "linkedin"
  }
}

The domain check

A request that carries an Origin or Referer header is checked against the form’s configured domain: Origin when both are there. A request with neither is treated as server-to-server and let through on the strength of the token alone.

Origin or Referer	Result
Absent	Allowed: server-to-server, the token is the credential
Present, host is `localhost`	Always allowed
Present, host matches the form’s domain, or a subdomain of it	Allowed
Present, host doesn’t match	`403 Forbidden`

Only hostnames are compared. The host is read out of the header value (so the scheme and any port are dropped), lowercased, and a leading www. removed. The form’s configured domain is normalised the same way: scheme, leading www. and any trailing slash come off first. A form saved as https://www.acme.test/ therefore matches a page served from https://acme.test/contact.

The OPTIONS preflight always answers 204, even for a token that doesn’t resolve to a form. So an unknown token doesn’t get blocked at this stage; the actual POST still goes through and comes back with the real 404 your JavaScript can read. A domain mismatch is different: the preflight for a token it does recognize carries that form’s own domain in its CORS header, not the calling page’s, so the browser refuses to send the POST at all. You’ll see a CORS failure in the console, never a 403: only a server-to-server call, which skips preflight entirely, gets that body directly.

An unknown token and an inactive form’s token fail identically, with the same 404. There’s no way to tell “wrong token” from “this form is turned off” from the response alone.

Responses

Every response from the submissions route:

Status	Body	When
`200 OK`	`{"status": "accepted"}`	The honeypot field was filled in, or this exact `fields` payload already arrived from the same address on the same form a moment ago: neither one is queued for processing
`201 Created`	`{"status": "accepted"}`	A genuine new submission was stored and queued
`403 Forbidden`	`{"error": "Script not authorized for this domain"}`	An `Origin` or `Referer` header was present and didn’t match the form’s domain
`404 Not Found`	`{"error": "Invalid form source"}`	The token doesn’t match a form, or the form isn’t active
`422 Unprocessable Entity`	`{"error": "Payload too large"}`	The whole request body is over the size limit
`422 Unprocessable Entity`	`{"error": "Invalid payload", "errors": {...}}`	The payload fails validation: `fields` is missing or has too many entries, or a `context` value runs over its length limit
`422 Unprocessable Entity`	`{"error": "Invalid payload"}`	A `fields` key or value doesn’t pass the shape check above
`429 Too Many Requests`	none of the shapes above: the rate limiter answers, not the endpoint	Too many requests for this token, from this address, in a short window

The checks run in that order: token, then domain, then body size, then validation. The first one that fails is the response you get.

Two different problems both come back as {"error": "Invalid payload"}. One is Laravel’s own validator failing. That one also carries an errors object naming the field. The other is a fields value that isn’t a plain scalar, or a name or value that’s too long, checked separately after the validator passes. It never gets an errors object. Check whether errors is present before assuming which one happened.

Honeypot and deduplication

Two things stop a submission before it is ever queued for processing, and they stop it in different ways:

_hp is a honeypot: real visitors leave it empty. Any value in it that isn’t blank marks the submission spam. The submission is still recorded, with that status, but nothing is queued.
The exact same fields sent again from the same IP address, to the same form, shortly after the first attempt doesn’t create a second submission. Nothing new is stored at all. Only fields is compared, so a different context on the retry (a different page, different UTM tags) doesn’t change that.

Both cases return the same 200 {"status": "accepted"} as a genuine success, so neither a spam script nor a retried request can tell it was caught.

Because a caught duplicate creates nothing, retrying a request you’re not sure landed is safe, but only for a little while after the original attempt. Wait too long before retrying and the second call creates a real, separate submission instead of being caught.

Form discovery

The capture script also reports the forms it finds on a page to /api/public/web-forms/{token}/forms: their fields, labels and how each one submits. We use that to build the list you map fields against in the product. A successful report answers 200 with {"status": "ok"}. A direct integration doesn’t need to call this route at all, unless it’s replicating what the script does. The token check, the domain check and the size limit are the same as on the submissions route. Posting a form’s key again refreshes what’s known about its fields, but never touches whether you’re tracking it or how its fields are mapped. Rediscovery can’t downgrade a form you’ve already set up.

Rate limit

Requests to this endpoint are throttled on their own, keyed by IP address and form token together: a different address posting to the same form, or the same address posting to a different form, each has its own budget. The submissions route and the discovery route share that budget: discovery calls from one address eat into what’s left for submissions from that same address. Go over it and further calls return 429 until the window clears.

Install methods: JavaScript snippet or direct endpoint

The exact script tag, the platform-specific guides, and the context fields each install method accepts.

Connect the forms on your website

Scan your site, map the fields, and turn on the form this token belongs to.

API overview

Where this endpoint sits next to the versioned lead-intake API.

​Endpoint

​Request body

​The domain check

​Responses

​Honeypot and deduplication

​Form discovery

​Rate limit

​Related

Install methods: JavaScript snippet or direct endpoint

Connect the forms on your website

API overview

Endpoint

Request body

The domain check

Responses

Honeypot and deduplication

Form discovery

Rate limit

Related