Case Create

Use this endpoint to create a case with recipients, settings, and documents for signing.

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}/case/create

Path Parameters

Parameter	Type	Description
`company`	`string`	Your company identifier

Request Body

Field	Type	Required	Description
`title`	`string`	Yes	Case title
`referenceId`	`string`	No	Internal reference ID
`folder`	`string`	No	Folder name
`autoSend`	`boolean`	No	Send immediately after creation
`customMessage`	`boolean`	No	Enable a custom recipient message
`message`	`string`	No	Custom recipient message
`user_email`	`string`	No	Sender email address
`emailtemplate`	`string`	No	Email template ID. An unknown id is ignored (see Template Not Found)
`settings`	`object`	Yes	Case settings
`signingSchemas`	`array`	No	Allowed signature methods
`recipients`	`array`	Yes	Recipient list
`documents`	`array`	Yes	Documents to sign
`tags`	`array`	No	Values filled into `{tag}` placeholders in `.docx` documents

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

Signing Schemas

urn:grn:authn:dk:mitid:substantial (MitID Privat with CPR match, only offered to recipients with needsCpr: true)
urn:grn:authn:dk:mitid:low (MitID Privat, only offered to recipients with needsCpr: false)
urn:grn:authn:dk:mitid:business
urn:grn:authn:se:bankid
urn:grn:authn:de:personalausweis
draw-cpr
draw
sms-email
approve (recipient-level only — see Approvers)

Each recipient is only offered the methods that fit their needsCpr. low and substantial are the same MitID Privat login without and with a CPR match, not two security levels, so a list with substantial but not low gives recipients without needsCpr no MitID Privat option at all. Send both and NextSign picks the right one per recipient. See Signing Schemas.

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 create endpoints
`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
`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. An unknown id falls back to the case template (see Template Not Found)
`message`	`string`	Custom recipient message
`eboks`	`object`	e-Boks delivery payload. See the e-Boks Object for `method`, `cvr`, `address`, and `name`

recipient.signingSchema accepts the same values listed under Signing Schemas.

If recipient.signingSchema is omitted, the recipient falls back to the case-level signingSchemas. If it is set, that recipient is locked to the selected method and cannot choose other signing options during signing.

If needsCpr is true and recipient.signingSchema is set, CPR verification still uses urn:grn:authn:dk:mitid:substantial before the signer continues with the forced signing method.

If needsCpr is true, you must also send recipient.cpr in the payload. If recipient.cpr is missing, the signer cannot complete CPR verification.

If you need the CPR number later in your own workflow, store it on your side as well. Do not rely on NextSign as a source for recovering the original plain-text CPR value after processing.

Example recipient with CPR validation:

{
  "name": "Andreas",
  "email": "al@nextsign.dk",
  "cpr": "190497xxxx",
  "needsCpr": true,
  "signing": true
}

Approvers

An approver reviews the documents and approves them with a single click — no eID, no signature. Approvals are logged (timestamp, IP, browser) but the approver never appears on the signed documents or the signature page. An approval or rejection is charged 0.5 credits instead of 1.

Create an approver by forcing the approve method on the recipient:

{
  "name": "Andreas",
  "email": "al@nextsign.dk",
  "signing": true,
  "signingSchema": "approve",
  "group": 1
}

Approvers participate in the signing order like signers: an approver in group 1 must approve before group 2 is contacted. If the approver rejects, the whole case is denied and the case owner is notified with the rejection reason.

approve cannot be used in the case-level signingSchemas list — it is a per-recipient method only. needsCpr is not supported for approvers.

Document Fields

Field	Type	Description
`name`	`string`	File name including extension
`file`	`string`	Hosted file URL, uploaded file URL, or base64 data
`fileIsBlob`	`boolean`	Set to `true` for base64 payloads. Omit it when using an uploaded file URL
`signObligated`	`boolean`	Whether signing is required
`documentMustBeRead`	`boolean`	Whether the document must be read before signing
`signatories`	`array`	Selected signatories
`mergeTags`	`boolean`	Set to `false` to leave this `.docx` out of the template-tag merge. See Template Tags

Documents can be PDF, Word (.docx), or iXBRL / XML (.xhtml, .html, .xml). iXBRL annual reports for the Danish Business Authority (Erhvervsstyrelsen) are supported and signed with an enveloped XAdES seal. See Accepted File Types.

If the combined size of the documents in a case is more than 3.5 MB, upload the files first with Document Upload and use the returned URL in documents[].file.

Template Tags

When the request body contains a non-empty tags array, every .docx in documents is rendered with those values before it is converted to PDF — {customer_name} in the Word file becomes the value you sent. PDF documents are never affected, and a request without tags converts each .docx as-is.

Field	Type	Description
`tag`	`string`	Tag name as written in the Word file, without braces
`value`	`string \| number \| array`	Value to insert
`type`	`string`	Tag type such as `text`, `number`, `date`, `condition`, or `array`
`name`	`string`	Optional human-readable label stored on the case
`sensitive`	`boolean`	Encrypt the value at rest on the case. The plain value is still used for the merge

See Template Tags for the {tag} placeholder syntax to write in the Word file, including conditional sections and lists.

Set mergeTags: false on an individual document to leave that file out of the merge. Use it for appendices that travel with the main contract but are not built from the same template — the file is converted to PDF unchanged, so unrelated { characters in it cannot break the render.

{
  "tags": [
    { "tag": "customer_name", "value": "Andreas", "type": "text" }
  ],
  "documents": [
    {
      "name": "Lejekontrakt.docx",
      "file": "BASE64_DATA",
      "fileIsBlob": true
    },
    {
      "name": "Bilag 1.docx",
      "file": "BASE64_DATA",
      "fileIsBlob": true,
      "mergeTags": false
    }
  ]
}

mergeTags only has an effect on this endpoint, and only on .docx documents in a request that also sends tags. Omitting it means the document takes part in the merge, so existing payloads keep their current behaviour.

Large Document Upload Flow

Upload the file with Document Upload
Take the url from the upload response
Pass that URL into documents[].file in the case creation payload

Example:

{
  "documents": [
    {
      "name": "Lejekontrakt.pdf",
      "file": "https://nextsign-dev.hel1.your-objectstorage.com/.../Lejekontrakt.pdf"
    }
  ]
}

Example Request

cURL

curl --location 'https://www.nextsign.dk/api/v2/{company}/case/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "title": "Lejeaftale",
    "referenceId": "Jrn. 2342-23",
    "folder": "Default",
    "autoSend": true,
    "customMessage": true,
    "message": "Kære {recipient_name}, som aftalt er hermed dokumenter til underskrift",
    "user_email": "info@nextengine.dk",
    "settings": {
      "reminders": {
        "send": true,
        "amount": 2,
        "daysBetween": 3
      },
      "lang": "da",
      "deletion": {
        "autoDelete": false,
        "days": 30
      },
      "availability": {
        "unlimited": true,
        "days": 10
      },
      "template": 2
    },
    "signingSchemas": [
      "urn:grn:authn:dk:mitid:low",
      "urn:grn:authn:dk:mitid:substantial",
      "urn:grn:authn:dk:mitid:business",
      "draw"
    ],
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@nextengine.dk",
        "signing": true,
        "group": 0,
        "redirectUrl": "https://example.com/complete",
        "signingSchema": "urn:grn:authn:dk:mitid:business"
      }
    ],
    "documents": [
      {
        "name": "Lejekontrakt.pdf",
        "file": "YOUR_BASE64_STRING_OR_URL",
        "fileIsBlob": true
      }
    ]
  }'

Example Response

200 OK

{
  "data": {
    "user": "65ab12cd34ef56ab78cd90ef",
    "nextSignKey": "7QmLp2Xs8HdNa4VrTc9YwKbJf",
    "realtime": false,
    "user_email": "api@example.com",
    "user_company": "65ab12cd34ef56ab78cd90a1",
    "title": "Lejeaftale",
    "referenceId": "REF-48392",
    "bin": false,
    "type": "Simple sign",
    "folder": "Default",
    "folderId": "65ab12cd34ef56ab78cd90a2",
    "signingSchemas": [
      "urn:grn:authn:dk:mitid:substantial",
      "urn:grn:authn:dk:mitid:low",
      "urn:grn:authn:dk:mitid:business",
      "urn:grn:authn:se:bankid",
      "draw-cpr",
      "draw"
    ],
    "settings": {
      "deletion": {
        "autoDelete": false,
        "days": 30
      },
      "availability": {
        "unlimited": false,
        "days": 10,
        "expiration": "2026-05-11T08:54:36.371Z",
        "isExpired": false
      },
      "reminders": {
        "send": true,
        "amount": 2,
        "daysBetween": 3
      },
      "template": 2,
      "lang": "da",
      "allowedRoles": [],
      "allowAPI": false,
      "allowRecipientsViewOthers": true
    },
    "recipients": [
      {
        "group": 0,
        "name": "Mia Sørensen",
        "needsCpr": false,
        "redirectUrl": "https://example.com/complete",
        "position": "Director",
        "cpr": "U2FsdGVkX18nR4mQ2Lp6YvZ8nT1aKs5JwP3eHx9LmNo=",
        "email": "mia.soerensen@example.com",
        "phone": "28123456",
        "sort": 0,
        "template": "",
        "type": "email",
        "signing": true,
        "signed": "pending",
        "signingToken": "Qp7Lm2Va9XrTc4Hs8KdNy5WbE",
        "signingSchema": "",
        "smsEmailVerification": {
          "attempts": 0
        },
        "signer": {
          "signer_type": "recipient",
          "identity": {
            "confirmed": false,
            "cprIsMatch": false
          }
        },
        "message": {
          "enable": true,
          "content": "Insert Custom message per Recipient here."
        },
        "uid": "pL8xRt2Q",
        "_id": "65ab12cd34ef56ab78cd90b1",
        "emailSent": [],
        "log": [],
        "emailEvents": [],
        "events": [],
        "url": "https://www.nextsign.dk/sign/65ab12cd34ef56ab78cd90b0/2/Qp7Lm2Va9XrTc4Hs8KdNy5WbE"
      }
    ],
    "integrations": {
      "microsoft": {
        "status": false
      },
      "uniconta": {
        "status": false
      }
    },
    "errorEmailSent": false,
    "reminders": {
      "allSigned": false,
      "createdAt": "2026-05-01T08:54:36.578Z"
    },
    "documents": [
      {
        "name": "Lejekontrakt.pdf",
        "file": "https://nextsign.hel1.your-objectstorage.com/65ab12cd34ef56ab78cd90a1/case/1777625676406-Lejekontrakt.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=R4ND0MCR3D3NT14LKEY1%2F20260501%2Fhel1%2Fs3%2Faws4_request&X-Amz-Date=20260501T085437Z&X-Amz-Expires=3600&X-Amz-Signature=9f1c2d3a4b5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
        "document_id": "https://nextsign.hel1.your-objectstorage.com/65ab12cd34ef56ab78cd90a1/case/1777625676406-Lejekontrakt.pdf",
        "signObligated": true,
        "documentMustBeRead": true,
        "signatories": [],
        "_id": "65ab12cd34ef56ab78cd90b2"
      }
    ],
    "roles": [
      "admin",
      "økonomi",
      "salg",
      "marketing",
      "standard",
      "it",
      "support",
      "hr"
    ],
    "message": "Kære {recipient_name}, som aftalt er hermed dokumenter til underskrift",
    "customMessage": true,
    "autoSend": true,
    "reminderAutoSend": true,
    "attachFiles": true,
    "source": {
      "type": "api"
    },
    "state": "open",
    "_id": "65ab12cd34ef56ab78cd90b0",
    "tags": [],
    "errors": [],
    "otherDocuments": [],
    "signedDocuments": [],
    "logs": [],
    "createdAt": "2026-05-01T08:54:36.581Z",
    "updatedAt": "2026-05-01T08:54:36.581Z",
    "__v": 0,
    "id": "65ab12cd34ef56ab78cd90b0"
  },
  "notices": [
    {
      "message": "No user id provided, adding the email.",
      "using": "65ab12cd34ef56ab78cd90ef"
    },
    {
      "message": "No user name provided"
    },
    {
      "message": "No roles provided - default roles used",
      "using": [
        "admin",
        "økonomi",
        "salg",
        "marketing",
        "standard",
        "it",
        "support",
        "hr"
      ]
    },
    {
      "message": "No email template provided - using default"
    }
  ]
}

Response Fields

Field	Type	Description
`data`	`object`	Created case object
`notices`	`array`	Non-fatal notices returned during processing

e-Boks Delivery Failures

An open case with autoSend on is sent before the response is returned, so an e-Boks recipient that e-Boks rejects (a CPR not registered for Digital Post, an address that cannot be resolved) is reported in notices. The status is still 200: the case exists, so do not retry the request.

{
  "code": "eboks-delivery-failed",
  "message": "e-Boks delivery to Andreas Lauridsen failed: invalid-address",
  "recipientId": "65ab12cd34ef56ab78cd90b1",
  "error": "invalid-address"
}

There is one notice per failed recipient. The same failure also fires the case.delivery.failed webhook.

If the invitation email could not be sent, the case is still created and the response is still 200, with this notice:

{ "code": "email-delivery-failed", "message": "The invitation email could not be sent" }

An e-Boks recipient is reached through e-Boks only: an email or phone on it is not used for an invitation.

Template Not Found

An unknown template id, for example a deleted template or a mistyped id, is ignored, and the case is still created with status 200. The case falls back to the default copy, and a recipient's template falls back to the case template. Each ignored id gets a notice that names the field:

{
  "code": "message-template-not-found",
  "field": "recipients[1].template",
  "message": "recipients[1].template was not found for this company and was ignored"
}

The v3 API rejects the request instead, with the message-template-not-found error.

Common Error Responses

Validation error:

{
  "errors": [
    {
      "message": "Missing recipients"
    }
  ],
  "notices": []
}

An e-Boks recipient without a CPR, CVR or address (see the e-Boks Object) is rejected before the case is created. This covers recipients that get the eboks type from the emailtemplate, and only recipients of type eboks:

{
  "errors": [
    {
      "message": "recipients[0].cpr is required for an e-Boks recipient, unless eboks.cvr or eboks.address is given",
      "recipient": 0,
      "field": "cpr"
    }
  ],
  "notices": []
}

Server error:

{
  "errors": [
    {
      "message": "Server error",
      "error": "Internal error details"
    }
  ]
}