API routing reference

The request Finerlise sends to your routing endpoint, and the replies it understands.

API routing is available on Enterprise.

Request

Finerlise sends a POST with a JSON body when the configured page is completed, or after submission:

{
  "event": "response.routing",
  "phase": "page",
  "createdAt": "2026-10-08T12:00:00.000Z",
  "formId": "3c9d2b1a-7e4f-4a6b-8c2d-1f0e9a8b7c6d",
  "formTitle": "Customer support",
  "responseId": null,
  "completedPage": {
    "id": "…",
    "sourceId": "…",
    "title": "Your account",
    "order": 0
  },
  "answers": [
    {
      "fieldId": "…",
      "label": "Customer ID",
      "type": "SHORT_TEXT",
      "value": "C-1042",
      "rawValue": "C-1042"
    }
  ],
  "values": { "<fieldId>": "C-1042" },
  "pages": [
    { "id": "…", "sourceId": "…", "title": "Priority support", "order": 1 }
  ],
  "endPages": [
    {
      "id": "…",
      "sourceId": "…",
      "name": "Book a call",
      "isDefault": false,
      "order": 0
    }
  ]
}

phase is page between pages and submission after the form is submitted. responseId is set in the submission phase.

Headers

Header	Value
`Content-Type`	`application/json`
`X-Finerlise-Event`	`response.routing`
`X-Finerlise-Signature`	`sha256=<hex HMAC-SHA256 of the raw body>`, using the routing secret (`fnr_route_…`)
Your custom headers	Up to 20, each up to 1,000 characters.

Verify the signature the same way as for webhooks.

Reply

Reply 200 with JSON (up to 64,000 characters) within your timeout (3–30 seconds). Redirects aren’t followed.

{
  "next": "Priority support",
  "fields": { "tier": "gold" }
}

Key	Meaning
`next` (or your response path, which can be nested like `routing.target`)	Where to go: a page title or ID, an end page name or ID, `end`/`submit`/`complete`, an `http(s)://` URL, or `next`/`default`. Matching is case-insensitive.
`fields`	Values for API response blocks, keyed by their API response key. Up to 50 keys; text, numbers or booleans up to 500 characters each.
`error`	A message (up to 280 characters), or `{ "message": "…" }`, shown to the respondent, who stays on the current page.

If the call fails, times out or returns something unreadable, the form continues along its default path.