Forms

Save Form Route

Set where this form's submissions go, and how its fields map.

SEND THE expected_* PRECONDITIONS. They are optimistic-concurrency guards, not settings: without them the save is last-writer-wins and can silently overwrite a colleague's route on a live form.

workflow_policy defaults to disabled. simulate records what WOULD have run without running it, which is the safe way to turn automation on for a form that is already receiving real submissions.

put/forms/{form_key}/route

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/forms/{form_key}/route
  • Auth: HTTP bearer

Path parameters

form_keystring required

Form key.

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

source_idstring required
target_list_idinteger required

Audience list submissions land in.

mappingobject[]

Form field -> graph8 field.

defaultsobject

Values applied to every submission.

workflow_policy'disabled' | 'simulate' | 'enabled'

Whether routed submissions trigger workflows. simulate records what WOULD have run without running it - the safe way to turn automation on for a live form. Defaults to disabled.

expected_schema_versioninteger nullable

PRECONDITION, not a setting. The form schema version this mapping was built against; the save is rejected if the form has changed shape since. Omitting it saves a mapping against a schema you have not seen.

schema_drift_approvedboolean

Save anyway when the schema HAS drifted. Deliberate override.

expected_current_route_versioninteger nullable

PRECONDITION. The route version you are replacing. Without it the save is last-writer-wins and can silently overwrite a colleague's route.

expected_route_history_versioninteger nullable

PRECONDITION on the route's history log.

Response

Successful Response

dataFormPayload required

An open envelope for a form operational view.

overview, fields, placements, activity, a route save result and a submission trace each return a different shape assembled from several upstreams. Pinning any of them would drop a field the moment one is added, and on a delivery-diagnostics surface a missing field reads as a missing delivery.

Changes

No recorded changes to this operation across all 2 revisions of this API.