Send a Webflow

Create a webflow from a published form and invite people to supply information, just as you do in the dashboard. The form defines the pages, questions, recipient roles, identity checks and what happens after completion. Creating a webflow does not immediately create a signing case.

POST https://api.nextsign.dk/v3/api/webflows

Before you start

Publish a form with webflow enabled in the dashboard. Use its form ID and the stable tag identifier of each recipient role, not the role's display name (tagName). Include every role exactly once, including roles that only sign later. At least one role must supply information.

Use an API key created by a user who is still a member of your company. That user is the sender. Forms and email templates must belong to the same company as the key. Unpublished changes are not used: each webflow stores a snapshot of the published form.

This endpoint sends email invitations to roles configured to supply information. SMS and other initial delivery channels are not supported by this endpoint.

Quickstart

Replace the form ID and role identifiers with values from your published form. This example assumes a form with one role, customer, and a field named order_number.

curl --request POST 'https://api.nextsign.dk/v3/api/webflows' \
  --header "Authorization: Bearer $NEXTSIGN_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-information-v1' \
  --data '{
    "formId": "65ab12cd34ef56ab78cd90b0",
    "title": "Information for order 1042",
    "referenceId": "order-1042",
    "recipients": [
      { "role": "customer", "name": "Alex Example", "email": "alex@example.com" }
    ],
    "values": { "order_number": "1042" }
  }'

Store the idempotency key alongside the operation in your system. Reuse that key and the same payload after a timeout or network failure.

Request

Unknown properties are rejected. Do not send company IDs, sender overrides, page definitions or uploaded document content here; configure the published form in the dashboard.

Each recipient accepts:

Template precedence is: recipient override → request override → role template → form's default invitation template → standard invitation. These are information-request emails, not the signing case's email templates.

values accepts strings (up to 20,000 characters), finite numbers, booleans and null. Arrays and objects are not accepted. Unknown tags are rejected. These values prefill the form; they do not mark questions answered or recipients complete. Sensitive/encrypted fields are encrypted in the saved webflow. Field rules still apply during form completion.

Response

First creation returns 201 Created with Location: /v3/api/webflows/{id}. A replay returns 200 OK with the same webflow's current status.

{
  "webflow": {
    "id": "65ab12cd34ef56ab78cd90b1",
    "formId": "65ab12cd34ef56ab78cd90b0",
    "title": "Information for order 1042",
    "referenceId": "order-1042",
    "state": "awaiting-responses",
    "createdAt": "2026-09-23T12:00:00.000Z",
    "completedAt": null,
    "caseId": null,
    "recipients": [
      {
        "id": "65ab12cd34ef56ab78cd90b2",
        "role": "customer",
        "name": "Alex Example",
        "email": "alex@example.com",
        "requiresResponse": true,
        "completed": false,
        "invitationStatus": "submitted",
        "formUrl": "https://app.nextsign.dk/webflow/65ab12cd34ef56ab78cd90b3/65ab12cd34ef56ab78cd90b1/65ab12cd34ef56ab78cd90b2",
        "answers": []
      }
    ]
  }
}

The formUrl host follows your environment. Treat each URL as a personal access credential: do not publish it or share it with another recipient. See Get a Webflow for response fields and answer retrieval.

Retries and invitation status

Idempotency-Key is required: 1–128 printable ASCII characters without spaces, unique per operation within your company. The same key and payload reuse the existing webflow and never resend invitations, including concurrent retries. A changed payload with the same key returns 409 idempotency-conflict. A new key creates a new webflow, even when referenceId is unchanged.

A newly created webflow returns 201 even if a send attempt has an unknown outcome. Inspect every recipient's status. Fetch the webflow again to check pending attempts; a replay does not retry them. Resolve uncertain delivery from the dashboard, or use the personal link through your own delivery process. Do not switch keys merely to retry an invitation.

A server error or timeout can occur after persistence. Retry with the same key and body to recover the webflow safely. Keep the key for the lifetime of the operation.

Errors

Standard authentication failures are described under Errors. Per-key scopes are not enforced yet, as described under Authorization.