Shared request and response objects used across cases, forms, and document endpoints.

Objects

Use this page as the shared reference for the most important payload objects reused across the NextSign API.

This is the canonical place to look up:

recipient fields
document fields
settings fields
signing schema values
case state values

Recipient Object

Used in:

Case Create
Case Update
Forms Submit
response payloads from Case Get and Forms Get

Common Request Fields

Field	Type	Description
`name`	`string`	Recipient name
`email`	`string`	Recipient email address
`signing`	`boolean`	Whether the recipient must sign
`group`	`number`	Preferred signing order/group. Lower numbers are invited first
`order`	`number`	Legacy alias for `group`
`needsCpr`	`boolean`	Whether CPR validation is required
`cpr`	`string`	CPR number. Required when `needsCpr` is `true`
`signingSchema`	`string`	Optional recipient-specific signing method override
`redirectUrl`	`string`	Redirect URL after signing
`phone`	`string`	Phone number for SMS-style delivery flows
`position`	`string`	Signature title or position
`type`	`string`	Delivery type. Common values are `email`, `sms`/`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`

Update-Only Fields

Field	Type	Description
`_id`	`string`	Existing recipient identifier when patching a recipient
`id`	`string`	Alias for `_id`
`clearCpr`	`boolean`	Set to `true` with an empty `cpr` value to clear stored CPR data

Common Response Fields

Field	Type	Description
`_id`	`string`	Recipient identifier
`uid`	`string`	Internal recipient uid used in document signatory mapping
`signed`	`string`	Recipient signing status such as `pending`, `signed`, `denied`, or `not signing`
`signingToken`	`string`	Recipient signing token
`url`	`string`	Direct signing URL. Returned for open cases

If recipient.signingSchema is omitted, the recipient falls back to the case-level signingSchemas.

If recipient.signingSchema is set, that recipient is locked to the selected method.

If needsCpr is true, you must also provide cpr.

If you need the plain CPR number later in your own workflow, store it on your side as well.

e-Boks Object

The eboks object is nested inside a recipient when type is set to eboks. It tells NextSign how to identify and reach the recipient inside the e-Boks system.

Fields

Field	Type	Required	Description
`method`	`string`	No	Identification method to use: `cpr`, `cvr`, or `address`. Defaults to `cpr` when omitted.
`cvr`	`string`	Conditional	CVR number for the recipient company. Required when `method` is `cvr`.
`address`	`string`	Conditional	Danish address string used to locate the recipient. Required when `method` is `address`. NextSign resolves the address into the underlying recipient details via the Danish address registry (dataforsyningen).
`name`	`string`	Conditional	Recipient name used alongside `address` for address-based delivery. Split into first name and last name by NextSign.
`kvhx`	`string`	No	Legacy KVHX identifier. Not required for current e-Boks delivery — the address is resolved server-side. See the note below.

Identification Methods

e-Boks delivery supports three ways to identify the recipient, selected with eboks.method. Set type: "eboks" on the recipient, then provide the field that matches the chosen method:

`method`	Identifier field	Notes
`cpr` (default)	`recipient.cpr`	10-digit CPR number for a private individual
`cvr`	`recipient.eboks.cvr`	8-digit CVR number for a company
`address`	`recipient.eboks.address`	Resolved server-side through the Danish address registry

CPR/CVR identification is the most reliable method. Address-based delivery requires that the address can be resolved unambiguously by the Danish address registry. You do not need to supply a kvhx value — sending the address string is enough.

If the field required by the selected method is missing (a valid CPR/CVR number, or a resolvable eboks.address), the delivery will fail with an invalid-recipient error.

kvhx is a legacy field retained for backwards compatibility. It is only consumed by the older direct-dispatch path and is ignored by the current e-Boks delivery flow, which resolves the recipient from the address string itself. New integrations should not send kvhx.

How the recipient name is resolved (address-based)

For address-based delivery, NextSign derives the recipient's first and last name from the recipient name field by splitting it on whitespace:

Two or more words — everything except the final word becomes the first name, and the final word becomes the last name. The recipient is addressed with both first and last name. (e.g. "Jane Marie Doe" → first name "Jane Marie", last name "Doe")
A single word — it is used as the first name only, with no last name. (e.g. "Jane" → first name "Jane")
Empty — the package is addressed to the resolved address without a personal name.

Because the last whitespace-separated token is treated as the last name, send the recipient name as First [middle] Last. A single-word name is delivered as a first name only.

Example — CPR-based delivery

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "type": "eboks",
  "signing": true,
  "needsCpr": true,
  "cpr": "1234567890",
  "eboks": {
    "method": "cpr"
  }
}

Example — CVR-based delivery

{
  "name": "Example Company ApS",
  "email": "kontakt@example.com",
  "type": "eboks",
  "signing": true,
  "eboks": {
    "method": "cvr",
    "cvr": "12345678"
  }
}

Example — Address-based delivery

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "type": "eboks",
  "signing": true,
  "eboks": {
    "method": "address",
    "address": "Østergade 12, 1100 København K",
    "name": "Jane Doe"
  }
}

Fallback to physical letter

When a company has the letter-fallback option enabled and e-Boks delivery fails, NextSign automatically retries by sending a physical letter through the letter dispatch service. A warning notification is created on the case when fallback is triggered.

Whether letter fallback is attempted depends on your NextSign account configuration. Contact NextSign support to enable or disable this option.

Document Object

Used in:

Case Create
Case Update
Document Convert
response payloads from case endpoints

Common Request Fields

Field	Type	Description
`name`	`string`	File name including extension
`file`	`string`	Hosted file URL, uploaded file URL, or base64 file data depending on the endpoint
`fileIsBlob`	`boolean`	Set to `true` when `file` contains base64 file data
`signObligated`	`boolean`	Whether signing is required for the document
`documentMustBeRead`	`boolean`	Whether the document must be read before signing
`signatories`	`array`	Selected signatories for the document

Common Response Fields

Field	Type	Description
`_id`	`string`	Stored document entry identifier
`document_id`	`string`	Stored document/file identifier
`file`	`string`	URL to the stored or converted file
`name`	`string`	Stored file name

For Document Convert, only name and file are required from this object.

If the combined case documents are more than 3.5 MB, upload them first with Document Upload and use the returned URL in file.

After any recipient has signed, Case Update rejects document additions. Re-send a new contract/case instead.

Settings Object

Used in:

Case Create
Case Update
Forms Submit
response payloads from Case Get and Forms Get

Field	Type	Description
`reminders.send`	`boolean`	Whether reminder messages should be sent
`reminders.amount`	`number`	Maximum number of reminders
`reminders.daysBetween`	`number`	Days between reminders
`deletion.autoDelete`	`boolean`	Whether the case should be automatically deleted later
`deletion.days`	`number`	Days before auto deletion
`availability.unlimited`	`boolean`	Whether the case should be available without an intended limit
`availability.days`	`number`	Days the case should stay available for signing
`availability.expiration`	`string`	ISO 8601 expiration timestamp managed by NextSign
`availability.isExpired`	`boolean`	Whether the case is currently expired
`template`	`number`	Signing page / document template selection
`lang`	`string`	Language code such as `da`, `en`, `de`, or `no`
`allowAPI`	`boolean`	Whether API usage is allowed in the related configuration context
`allowRecipientsViewOthers`	`boolean`	Whether recipients may view other participants
`allowedRoles`	`array`	Allowed roles list, primarily used with forms

On case create and case update, NextSign recalculates availability.expiration from availability.days.

availability.expiration and availability.isExpired are managed by NextSign and should be treated as system values in responses.

Signing Schemas

Used in:

Value	Name	CPR Required	Notes
`urn:grn:authn:dk:mitid:low`	MitID Privat	No	Standard MitID private signing
`urn:grn:authn:dk:mitid:substantial`	MitID Privat	Yes	MitID private signing with CPR verification
`urn:grn:authn:dk:mitid:business`	MitID Erhverv	No	MitID business signing
`urn:grn:authn:se:bankid`	BankID SE	No	Swedish BankID signing
`urn:grn:authn:de:personalausweis`	Personalausweis	No	German national eID card (Personalausweis) signing
`draw`	Touch	No	Drawn signature without CPR verification
`draw-cpr`	Touch	Yes	Drawn signature with CPR verification
`sms-email`	SMS + Email verification	No	NextSign-hosted verification flow

At the case level, signingSchemas defines the allowed signing methods for the case.

At the recipient level, recipient.signingSchema forces one specific method for that signer.

After any recipient has signed, Case Update rejects signingSchemas changes. Re-send a new contract/case instead.

Case States

Used in:

Canonical Lifecycle Values

Value	Meaning
`draft`	The case exists but is not open for signing yet
`open`	The case is active and can be signed
`completed`	The case has been fully completed or manually marked as completed
`denied`	The case has been denied during the signing flow
`cancelled`	The case has been cancelled

Accepted Aliases On Case Update

Value	Maps To
`pending`	`open`
`signed`	`completed`

The status filter on Case List is a different concept. It currently filters by derived signing progress (pending, signed, denied) rather than the stored lifecycle state.