Migrating from v2

This page maps v2 Case Create onto v3 Create a Case and lists the behaviour that differs.

Start here

Three changes will affect almost every existing payload:

1. Unknown fields are rejected. Anything v2 quietly ignored is now a 400. Expect your first v3 request to fail, and read the details array — it names every field at once.
2. recipients[].signing now defaults to true. In v2 it defaults to false. If you relied on that, set "signing": false explicitly on observers.
3. Cases expire in 30 days by default, not 90. Send settings.expiresInDays if you depended on v2's default.

Endpoint and envelope

Field mapping

Case

Recipients

Documents

Behaviour differences

Things that will change your results

Cases expire in 30 days by default, not 90. v2's 90 was an API-only outlier; every other part of NextSign uses 30.

recipients[].signing defaults to true. Omitting it in v2 creates a case nobody can sign, with no warning.

The signing page language follows your company, then falls back to Danish. v2 always used Danish for API-created cases regardless of company settings.

Sequential signing works. v2 never set the group cursor on API-created cases, so group ordering did not gate correctly. v3 sets it, and it is returned as activeGroup.

An unknown folder is an error. v2 silently files the case in the default folder — which has a different role list, so the case ends up visible to a different set of colleagues.

Unrecognised file content is rejected — when you send the bytes. v2 stored anything it could not identify as a PDF, so a JPEG became a "PDF" that broke the signing page later. v3 inspects content and rejects anything that is not a PDF or a real .docx. A document sent as a url is still stored by reference and not inspected, in v3 as in v2.

roles cannot be sent. In v2 a client-supplied roles array widens who inside your company can see the case, bypassing the folder's access list.

Sender attribution never guesses silently. With no user, v2 assigns the case to whichever company user sorts first. v3 uses the user you name in senderId or senderEmail; with neither, it falls back to the person who created the key and tells you so in notices. A key with no user behind it is rejected outright.

You cannot set a sender name or email freely. v2 takes user_name and user_email straight from the payload, so a case can claim to come from any address. In v3 those values are read from the named user's NextSign profile.

Things that make failures easier to handle

A 4xx means nothing was created. v2 can return 500 for a case that exists and has already been emailed, because sending happens after the save and is not isolated — retry that and you get a duplicate. v3 has no such window; see Errors.

Send failures are reported, not thrown. A failed email comes back as delivery.email.ok: false on a 201.

One contact failure no longer fails the case. v2 aborts the whole creation if a recipient cannot be written to your contact list.

All validation errors arrive together, each with a field path.

Response differences

v3 returns a defined object rather than the raw database document, so signingToken, nextSignKey, encrypted cpr, signer, logs, events, roles and __v are no longer present.

Worked example

v2:

{
  "title": "Lejeaftale",
  "user_email": "info@example.com",
  "settings": {
    "lang": "da",
    "availability": { "days": 14 },
    "reminders": { "send": true, "amount": 2, "daysBetween": 3 }
  },
  "recipients": [
    { "name": "Andreas", "email": "al@example.com", "signing": true, "order": 0 }
  ],
  "documents": [
    { "name": "Lejekontrakt.pdf", "file": "JVBERi0...", "fileIsBlob": true }
  ]
}

v3:

{
  "title": "Lejeaftale",
  "senderEmail": "anna@example.com",
  "settings": {
    "language": "da",
    "expiresInDays": 14,
    "reminders": { "send": true, "amount": 2, "daysBetween": 3 }
  },
  "recipients": [
    { "name": "Andreas", "email": "al@example.com", "group": 0 }
  ],
  "documents": [
    { "name": "Lejekontrakt.pdf", "content": "JVBERi0..." }
  ]
}

Suggested rollout

Related