Create a Case

Creates a case with its recipients and documents, and — unless you ask for a draft — sends it.

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

Authenticated with an API key — see Authorization.

Quickstart

The smallest request that creates and sends a case: a title, one recipient, one document.

curl https://api.nextsign.dk/v3/api/cases \
  -H "Authorization: Bearer $NEXTSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rental agreement",
    "recipients": [{ "name": "Andreas Lauridsen", "email": "al@example.com" }],
    "documents": [{ "name": "contract.pdf", "content": "JVBERi0xLjQK..." }]
  }'

const response = await fetch('https://api.nextsign.dk/v3/api/cases', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NEXTSIGN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Rental agreement',
    recipients: [{ name: 'Andreas Lauridsen', email: 'al@example.com' }],
    documents: [{ name: 'contract.pdf', content: pdfBuffer.toString('base64') }],
  }),
});

const { case: created } = await response.json();
console.log(created.recipients[0].signingUrl);

import base64, os, requests

pdf = base64.b64encode(open("contract.pdf", "rb").read()).decode()

response = requests.post(
    "https://api.nextsign.dk/v3/api/cases",
    headers={"Authorization": f"Bearer {os.environ['NEXTSIGN_API_KEY']}"},
    json={
        "title": "Rental agreement",
        "recipients": [{"name": "Andreas Lauridsen", "email": "al@example.com"}],
        "documents": [{"name": "contract.pdf", "content": pdf}],
    },
)

created = response.json()["case"]
print(created["recipients"][0]["signingUrl"])

You get back 201 with the whole case, including a signing link per recipient. This is the complete body — nothing is elided:

{
  "case": {
    "id": "65ab12cd34ef56ab78cd90b0",
    "referenceId": null,
    "title": "Rental agreement",
    "state": "open",
    "language": "da",
    "createdAt": "2026-07-27T14:48:36.356Z",
    "expiresAt": "2026-08-26T14:48:36.356Z",
    "folder": { "id": "65ab12cd34ef56ab78cd90a2", "name": "Default" },
    "sender": {
      "id": "65ab12cd34ef56ab78cd90ef",
      "name": "Anna Beck",
      "email": "anna@example.com"
    },
    "activeGroup": 0,
    "recipients": [
      {
        "id": "65ab12cd34ef56ab78cd91a1",
        "uid": "4t5ZQbtB",
        "name": "Andreas Lauridsen",
        "email": "al@example.com",
        "phone": "",
        "position": "",
        "group": 0,
        "type": "email",
        "signing": true,
        "status": "pending",
        "needsCpr": false,
        "signingSchema": "",
        "signingUrl": "https://www.nextsign.dk/sign/65ab12cd34ef56ab78cd90b0/2/h6gKDYSiPyYTC5Bkq6urKfKKW"
      }
    ],
    "documents": [
      {
        "id": "65ab12cd34ef56ab78cd92c3",
        "name": "contract.pdf",
        "type": "application/pdf",
        "url": "https://nextsign-de.fsn1.your-objectstorage.com/65ab/contract.pdf",
        "signObligated": true,
        "documentMustBeRead": false,
        "signatories": []
      }
    ],
    "delivery": {
      "attempted": true,
      "email": { "ok": true },
      "eboks": { "ok": true },
      "sms": { "ok": true },
      "webhook": { "ok": true }
    },
    "notices": [
      {
        "code": "sender-defaulted-to-key-creator",
        "message": "Neither senderId nor senderEmail was provided. The case was attributed to the API key's creator (anna@example.com)."
      },
      {
        "code": "default-signing-schemas",
        "message": "No settings.signingSchemas provided — the standard eIDs were used.",
        "using": [
          "urn:grn:authn:dk:mitid:low",
          "urn:grn:authn:dk:mitid:substantial",
          "urn:grn:authn:dk:mitid:business",
          "urn:grn:authn:se:bankid",
          "urn:grn:authn:de:personalausweis"
        ]
      }
    ]
  }
}

The two notices are there because the request left something out. Neither is a problem — each one tells you what was chosen on your behalf:

• sender-defaulted-to-key-creator — no senderId or senderEmail was sent, so the case is owned by whoever created the API key. See Sender
• default-signing-schemas — no settings.signingSchemas were sent, so the standard eIDs apply. The using array lists exactly which ones

Everything else on this page is optional refinement of that request.

Query Parameters

One parameter, and it shapes the response rather than the case:

It is a query parameter rather than a body field because nothing about it is stored — the same body always creates the same case, whatever you ask the response to look like.

Request Body

A draft may legitimately be incomplete — no recipients, no documents — exactly like a case started in the dashboard and finished later. An open case is going out, so both are required.

Settings

Everything that shapes how the case behaves — as opposed to what it contains and who it involves — lives in the settings object:

{
  "settings": {
    "language": "da",
    "expiresInDays": 14,
    "reminders": { "send": true, "amount": 2, "daysBetween": 3 }
  }
}

Every field is optional, and so is the object itself — omit settings entirely and the case follows your company's defaults.

Recipients

Sequential signing. Recipients in group 0 are contacted first; group 1 is contacted only once every signer in group 0 has signed, and so on. Recipients with the same group are contacted together.

Documents

Each document needs a name and exactly one source: url, content, or documentId. Sending two sources is a 400 — accepting several and picking a winner is how a caller ends up sending a different file than they thought.

signatories are positions in your recipients array, so [0, 2] means the first and third recipient. An index outside the array is a 400, not a silent drop.

File sources

The three sources are not checked the same way, and the difference matters.

content is inspected. It must decode to a PDF or a .docx; the bytes decide, and the file name and any declared type are ignored. Anything else is a 400.

The stored file name follows the content. Upload PDF bytes named contract.docx and the document is stored and displayed as contract.pdf.

url is stored by reference. We do not download it while creating the case, so its contents are not inspected and a URL that 404s is still accepted — you will find out at signing time, not at creation time. Make sure it resolves, and stays resolving, for as long as the case is open.

documentId comes from your library, and is produced and converted the same way the dashboard does it — see Library documents.

A .docx you supply as content or url is converted to PDF before it is attached. If the case has a top-level tags array, those values are merged into it during that conversion.

Library documents

A documentId attaches a document from Dashboard → Documents. Find the id with List Documents; the document must be one your key can see — the company's non-private documents, the ones the key's user created, and documents shared with you — or it is document-not-found.

A .docx in the library is a template, and documents[].tags fills its fields. The keys are the field paths Retrieve a Document lists, and the values are checked against the document before anything is created: unknown keys, values for automatic (global, hidden or computed) fields, wrong types, values outside the author's bounds, and missing required fields all come back as validation-failed, with paths like documents[0].tags.start_date. A pdf document has no fields, so any tags key for it is rejected. The rules are the same as on Create a Case from a Document, which is the simpler endpoint when the case is built around one template.

name is still required on a library document, but the attached file keeps the library version's own name — a .docx becomes .pdf once rendered. On a draft the document is attached by reference with the values still editable in the dashboard, and rendered when the draft is sent.

Files over 20 MB

Upload the file first with Document Upload, then pass the returned URL as url:

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

Sender

The sender owns the case. That decides two real things: which colleagues can see it — through the folder's role list — and who the signing email says it came from.

Name one in either of two ways:

{ "senderId": "65ab12cd34ef56ab78cd90ef" }

Send both and senderId wins — an id identifies a user exactly, where an address is only a way of looking one up.

The user must be a member of your company. Anyone else — including a valid user id from another company — is rejected:

{
  "error": "sender-user-not-found",
  "details": [{ "field": "senderId", "message": "not a member of this company" }]
}

If you send neither

The case is attributed to whoever created the API key, and the response tells you so:

{
  "code": "sender-defaulted-to-key-creator",
  "message": "Neither senderId nor senderEmail was provided. The case was attributed to the API key's creator (anna@example.com)."
}

That is a sensible default for a key that belongs to one person. If a single key serves a whole team, name the sender on every request — otherwise every case is owned by, and appears to come from, the colleague who happened to create the key.

Folders

folder accepts a folder name or id. It must match a folder that exists:

{
  "error": "invalid-folder",
  "details": [{ "field": "folder", "message": "no folder named or with id 'Contracts'" }]
}

The case's role visibility always comes from the folder.

Presets

presetId applies your company's preset — folder, message template, language, signing schemas, reminders, expiry and file attachment policy.

A preset fills in whatever you did not send. If the preset has locked a field, it overrides the value you sent, because presets are how a company enforces signing policy.

settings.reminders.autoSend is never locked by a preset — a preset governs whether reminders happen, not which system dispatches them.

Reminders

settings.reminders is the reminder policy for the case:

Fields are merged individually, so {"reminders": {"daysBetween": 10}} keeps the default send and amount.

Logo

Puts your own logo on the signing page, for this case only.

{ "settings": { "logo": "iVBORw0KGgoAAAANSUhEUgAA..." } }

settings.logo accepts either base64 PNG or JPEG data, or a logo URL previously returned by NextSign. Base64 data is validated by content and stored for you; the case then carries the hosted URL. Maximum 8 MB of base64, which is roughly a 6 MB image.

Arbitrary third-party URLs are rejected — a signing page must not depend on a resource we do not control, which can change or disappear long after the case is signed.

If the upload itself fails, the case is still created and you get a signing-page-logo-not-stored notice rather than an error. A logo is decoration; losing it is not worth failing a signing case over.

Integrations

{ "settings": { "integrations": { "microsoft": { "returnPath": "/sites/MySite/Shared Documents" } } } }

returnPath is where signed documents are written back in SharePoint, when your company has an active SharePoint integration. It must be a site-relative path beginning with /. If there is no active integration the field is ignored and you get a notice rather than an error.

Signing Schemas

Case-level settings.signingSchemas lists the methods recipients may choose from. Omit it and the standard eIDs are used.

A recipient's own signingSchema locks that recipient to one method. If needsCpr is also set, CPR verification still runs through MitID substantial first.

Languages

Omit settings.language and the case follows your company's default.

Full Example

curl --location 'https://api.nextsign.dk/v3/api/cases' \
  -H "Authorization: Bearer ${NEXTSIGN_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "title": "Lejeaftale",
    "referenceId": "Jrn. 2342-23",
    "folder": "Default",
    "senderEmail": "anna@example.com",
    "settings": {
      "language": "da",
      "expiresInDays": 14,
      "message": "Kære {recipient_name}, som aftalt er hermed dokumenter til underskrift",
      "reminders": { "send": true, "amount": 2, "daysBetween": 3 },
      "signingSchemas": [
        "urn:grn:authn:dk:mitid:substantial",
        "urn:grn:authn:dk:mitid:business"
      ]
    },
    "recipients": [
      {
        "name": "Andreas Lauridsen",
        "email": "al@example.com",
        "group": 0,
        "position": "Director",
        "redirectUrl": "https://example.com/complete"
      },
      {
        "name": "Mia Sørensen",
        "email": "mia@example.com",
        "group": 1
      }
    ],
    "documents": [
      {
        "name": "Lejekontrakt.pdf",
        "content": "JVBERi0xLjQKJeLjz9M...",
        "signObligated": true,
        "signatories": [0, 1]
      }
    ]
  }'

{
  "case": {
    "id": "65ab12cd34ef56ab78cd90b0",
    "referenceId": "Jrn. 2342-23",
    "title": "Lejeaftale",
    "state": "open",
    "language": "da",
    "createdAt": "2026-07-27T14:48:36.356Z",
    "expiresAt": "2026-08-10T14:48:36.356Z",
    "folder": { "id": "65ab12cd34ef56ab78cd90a2", "name": "Default" },
    "sender": {
      "id": "65ab12cd34ef56ab78cd90ef",
      "name": "Anna Beck",
      "email": "anna@example.com"
    },
    "activeGroup": 0,
    "recipients": [
      {
        "id": "65ab12cd34ef56ab78cd91a1",
        "uid": "4t5ZQbtB",
        "name": "Andreas Lauridsen",
        "email": "al@example.com",
        "phone": "",
        "position": "Director",
        "group": 0,
        "type": "email",
        "signing": true,
        "status": "pending",
        "needsCpr": false,
        "signingSchema": "",
        "signingUrl": "https://www.nextsign.dk/sign/65ab12cd34ef56ab78cd90b0/2/h6gKDYSiPyYTC5Bkq6urKfKKW"
      },
      {
        "id": "65ab12cd34ef56ab78cd91a2",
        "uid": "9kPmR2xW",
        "name": "Mia Sørensen",
        "email": "mia@example.com",
        "phone": "",
        "position": "",
        "group": 1,
        "type": "email",
        "signing": true,
        "status": "pending",
        "needsCpr": false,
        "signingSchema": "",
        "signingUrl": "https://www.nextsign.dk/sign/65ab12cd34ef56ab78cd90b0/2/Rr8tVqLmXnPzB4dYw2sKfHjNe"
      }
    ],
    "documents": [
      {
        "id": "65ab12cd34ef56ab78cd92c3",
        "name": "Lejekontrakt.pdf",
        "type": "application/pdf",
        "url": "https://nextsign-de.fsn1.your-objectstorage.com/65ab/Lejekontrakt.pdf",
        "signObligated": true,
        "documentMustBeRead": false,
        "signatories": ["4t5ZQbtB", "9kPmR2xW"]
      }
    ],
    "delivery": {
      "attempted": true,
      "email": { "ok": true },
      "eboks": { "ok": true },
      "sms": { "ok": true },
      "webhook": { "ok": true }
    },
    "notices": []
  }
}

The Location response header carries the case path.

Response fields

Delivery

delivery reports each channel independently:

{ "attempted": true, "email": { "ok": false, "error": "ECONNREFUSED" }, "eboks": { "ok": true }, "sms": { "ok": true }, "webhook": { "ok": true } }

• attempted: false — nothing was sent. Either the case is a draft, or settings.autoSend was false. The key is still present, so read attempted rather than testing whether delivery exists
• webhook — appears on every open case, including one created with autoSend: false. Your integration is told the case exists even when we did not mail anyone
• ok: false — that channel failed. The case still exists, and the response is still 201

A failed channel is never reported as a failed request. Returning an error for a case that exists — and may already have been emailed — is what makes an integrator retry into duplicates.

Notices

{ "code": "sender-defaulted-to-key-creator", "message": "Neither senderId nor senderEmail was provided. …" }

Notices tell you something was defaulted, ignored or degraded. They never mean the request failed. Log them; do not branch on them. The full list is in Errors.

Document URLs

documents[].url is the document's stored address. It identifies the file and is stable, but it is protected — fetching it without credentials returns 403.

Add ?publicUrls=true for downloadable links, valid for one hour:

curl "https://api.nextsign.dk/v3/api/cases?publicUrls=true" \
  -H "Authorization: Bearer $NEXTSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Rental agreement", … }'

{ "url": "https://nextsign-de.fsn1.your-objectstorage.com/65ab/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=fa2ca5b25…" }

They are opt-in because they expire: a link minted at creation is dead an hour later, so storing one alongside the case leaves you with something that no longer works. The case id does not expire — ask for a fresh link with Retrieve a Case when you actually need to download.

Documents you supplied as a url are returned exactly as you gave them, with or without this parameter. We store those by reference and never re-host them, which is also why their type is null — we never fetched the bytes to inspect.

A .docx you upload is converted to PDF on the way in, so its name comes back as .pdf and its type as application/pdf. Both describe the file at url, not what you sent.

Errors

{
  "error": "validation-failed",
  "details": [
    { "field": "title", "message": "is required" },
    { "field": "recipients[0].email", "message": "must be a valid email" },
    { "field": "documents[0]", "message": "requires one of: url, content, documentId" },
    { "field": "nmae", "message": "unknown field" }
  ]
}

Structural problems in the body come back at once, so you fix them in one round-trip rather than one per deploy. A document's content is checked for being a real PDF or .docx once the structure is valid — see Validation returns everything at once.

Every 4xx from this endpoint means nothing was created. The case is persisted only after all of these have passed, so a 4xx is always safe to fix and resend. Full detail in Errors.

Related