Forms Submit

Use this endpoint to submit a form with tag values and recipients. A successful submission creates a case from the form configuration.

Authorization

All requests to this endpoint require authentication using a Bearer Token.

Use your NextSign API key as the bearer token for this endpoint.

Endpoint

POST https://www.nextsign.dk/api/v2/{company}/forms/{form_id}/submit

Path Parameters

Parameter	Type	Description
`company`	`string`	Your company identifier
`form_id`	`string`	Unique identifier of the form to submit

Request Body

Field	Type	Required	Description
`title`	`string`	No	Override the default form title
`customMessage`	`boolean`	No	Whether to use a custom message
`message`	`string`	No	Custom message shown to recipients
`user_name`	`string`	No	Sender name
`user_email`	`string`	No	Sender email
`state`	`string`	No	Case state. Omit (or pass `open`) for a normal case that is created and sent. Pass `draft` to create the case as a draft that is not sent. See Draft submissions.
`autoSend`	`boolean`	No	Whether to send the case to its recipients. Defaults to `true`, except when `state` is `draft` (then it defaults to `false`). Pass it explicitly to override.
`signingSchemas`	`array`	No	Allowed signature methods
`settings`	`object`	No	Case settings override
`folder`	`string`	No	Destination folder
`tags`	`array`	Yes	Tag values to inject into the form
`recipients`	`array`	Yes	Recipient list for the generated case

Shared object reference: Settings Object, Signing Schemas, Recipient Object, and Case States.

The structure of settings, signingSchemas, and recipient objects follows the same pattern as Case Create, including optional recipient.signingSchema overrides.

Recipient Fields

Field	Type	Description
`name`	`string`	Recipient name
`email`	`string`	Recipient email
`signing`	`boolean`	Whether the recipient must sign
`group`	`number`	Preferred signing order/group. Lower numbers are invited first
`order`	`number`	Legacy alias for `group` on forms submit
`needsCpr`	`boolean`	Whether CPR validation is required
`cpr`	`string`	Recipient CPR number. Required when `needsCpr` is `true`
`signingSchema`	`string`	Optional recipient-specific signing method override
`redirectUrl`	`string`	Redirect URL after signing. Must be sent inside the recipient object, and is returned back on `contract.recipients[].redirectUrl` in the response
`phone`	`string`	Phone number for SMS delivery
`position`	`string`	Signature title/position
`type`	`string`	Delivery type. Supported values are `email`, `phone`, and `eboks`
`template`	`string`	Optional recipient-specific template id
`message`	`string`	Custom recipient message
`eboks`	`object`	e-Boks delivery payload. See the e-Boks Object for `method`, `cvr`, `address`, and `name`

If a submitted recipient uses needsCpr: true, you must also provide recipient.cpr. See Case Create for the full recipient schema and CPR handling notes.

Draft submissions

By default a submission is created and sent to its recipients — the case is created with state open and signing invitations go out immediately.

To create the case as a draft instead — saved but not sent, so it can be reviewed or finished later — pass state: "draft":

The case is created with state draft and no signing emails or SMS are sent.
The response message is Contract created (instead of Contract created and sent), and the contract.recipients[].url signing links are not included, since a draft is not open for signing yet.
The draft appears alongside your other in-progress cases and can be opened, completed and sent later.

If you do not send state (or send state: "open"), the submission keeps the default behaviour and is sent off as normal.

state: "draft" implies autoSend: false. You can override this by sending autoSend explicitly — for example state: "draft" together with autoSend: true to create a draft-state case that is still sent.

Example Request

cURL

curl --location 'https://www.nextsign.dk/api/v2/{company}/forms/{form_id}/submit' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "title": "Ny Kontrakt",
    "state": "open",
    "tags": [
      {
        "tag": "kunde_fornavn",
        "value": "Andreas",
        "type": "text"
      },
      {
        "tag": "generel_price",
        "value": 4500,
        "type": "number"
      }
    ],
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@nextengine.dk",
        "signing": true,
        "group": 0,
        "redirectUrl": "https://example.com/complete",
        "signingSchema": "draw"
      }
    ]
  }'

Example — draft submission

cURL

curl --location 'https://www.nextsign.dk/api/v2/{company}/forms/{form_id}/submit' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "title": "Kladde kontrakt",
    "state": "draft",
    "tags": [
      {
        "tag": "kunde_fornavn",
        "value": "Andreas",
        "type": "text"
      }
    ],
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@nextengine.dk",
        "signing": true,
        "group": 0
      }
    ]
  }'

200 OK — draft

{
  "status": "OK",
  "message": "Contract created",
  "contract": {
    "_id": "66263484e601d81006d1a132",
    "title": "Kladde kontrakt",
    "state": "draft",
    "folder": "Default",
    "type": "Simple sign",
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@nextengine.dk"
      }
    ]
  }
}

Example Response

200 OK

{
  "status": "OK",
  "message": "Contract created and sent",
  "contract": {
    "_id": "66263484e601d81006d1a132",
    "title": "Ny Kontrakt",
    "folder": "Default",
    "type": "Simple sign",
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@nextengine.dk",
        "redirectUrl": "https://example.com/complete",
        "url": "https://www.nextsign.dk/sign/66263484e601d81006d1a132/2/WGOfO-7xvoh-5LPvK-O9cVt-Q1GnY"
      }
    ],
    "createdAt": "2024-04-22T09:57:24.498Z",
    "updatedAt": "2024-04-22T09:57:24.498Z"
  }
}

Response Fields

Field	Type	Description
`status`	`string`	Request status, typically `OK`
`message`	`string`	Human-readable result message
`contract`	`object`	Created case object

For open cases, the response includes contract.recipients[].url, which is the direct signing URL for each recipient.

If you submitted recipient.redirectUrl, the same value is returned on contract.recipients[].redirectUrl for that recipient.

Common Error Responses

Validation error:

{
  "message": "Bad request",
  "errors": [
    "No ID provided"
  ]
}

Form not found:

{
  "errors": [
    {
      "code": 400,
      "message": "Bad Request",
      "description": "Form not found"
    }
  ]
}