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 such as `open`
`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

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 such as `kvhx`, `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.

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 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"
    }
  ]
}