Skip to main content
A package is the central object in the NSEV WebPortal API. Everything you create when preparing something for signing hangs off a package: the documents to be signed, the people involved, the fields they interact with, and the order in which they act. This page explains how those objects relate so the API reference reads as a coherent whole rather than a list of endpoints.

​
The object hierarchy

A package contains four kinds of child object:
  • Documents - the files to be signed or filled in.
  • Stakeholders - the parties with an interest in the package (a person, or a group).
  • Actors - the specific actions a stakeholder must take (sign, approve, fill, receive). Actors belong to a stakeholder.
  • Elements - the fields placed on a document (signing fields and form fields). Elements are linked to the actor that interacts with them.
A separate object, the process, arranges the actors into the order in which they act.
A package is built up while it is in Draft status. Uploading documents, adding stakeholders, creating actors, and placing elements are all draft-only operations. Activating the package (by setting its status to pending) freezes the structure and starts the signing flow. See Best Practices → Package lifecycle for the required order of these steps.

​
Stakeholders

A stakeholder is an entity that has an interest in a package. A single stakeholder can carry multiple actors - that is, multiple actions it must take on the package. There are three stakeholder types, selected with the Type property when you create one:

Person

A single individual. Only that person can act on the package.

Group

A group of people, defined inline through Members. Any one member can act on behalf of the whole group.

ContactGroup

References a contact group already created in the WebPortal, by its ContactGroupCode, instead of listing members inline.
Person is the common case: you supply the individual’s name, email, language, and (where required) date of birth, and that person alone receives the action. Group lets several people share one action. You define the members inline in the create call, and each member receives a unique URL to complete the action. As soon as one member acts, the others can no longer act - the group’s action is done. Group members are described with the same fields as a person. ContactGroup behaves like a group, but instead of listing members in the request you reference a contact group that was already created in the WebPortal, passing its ContactGroupCode. The members come from that contact group rather than from your request body. A ContactGroup stakeholder only exists while the package is in draft. When the package moves to pending, a ContactGroup stakeholder is converted into a Group stakeholder; the contact group code is retained on the converted stakeholder.

​
The undecided stakeholder

A package can also report a stakeholder of type Undecided. This is the implicit placeholder a package carries before a real stakeholder has been assigned to an action. It is not something you create directly, and it cannot be deleted.

​
A stakeholder is not a Contact

It is easy to assume a stakeholder maps to a saved Contact, but the API has no Contact resource. Contacts exist only in the WebPortal UI, as an address-book convenience for people setting up packages by hand. When a Contact is used to set up a package, it ultimately becomes an ordinary Person stakeholder on that package - the same object you create directly through the API. So when you add a stakeholder via the API, you are always defining the party on the package itself, not referencing an address-book entry.
The one place the WebPortal’s saved entities surface in the API is the ContactGroup stakeholder type, which references a contact group by its ContactGroupCode - and even that is converted to a plain Group stakeholder when the package is activated.

​
Actors

An actor represents a single action that a stakeholder must take on the package. A stakeholder can have more than one actor (for example, the same person might both approve and sign). There are four actor types: Which elements an actor can carry depends on its type: signing fields can only be linked to Signers, and form fields (text boxes, checkboxes, radio groups) can only be linked to FormFillers. Approvers and Receivers do not interact with elements.

​
Actor status

Each actor reports a Status that tracks its action through the flow:

​
Reassigning an actor

If the person appointed to an action becomes unavailable, an actor can be reassigned to a new Person stakeholder. Reassignment always targets a person (not a group), and you supply a reason for the reassignment. Where the original action used mandated signing, the replacement may need to supply the same additional identity properties (see Additional properties).

​
Elements

Elements are the fields placed on a document’s pages. They come in two families:
  • Signing fields - mark where a signature must be placed. Signing fields are always mandatory, and they belong to a Signer actor.
  • Form fields - inputs an end user fills in, belonging to a FormFiller actor. There are three form-field types: TextBoxField (free text), CheckBoxField (a toggle), and RadioGroup (a set of mutually exclusive options).
An element can be placed (positioned on a specific page of a specific document) or unplaced (created on the package without a position, to be positioned later - for example through the Package Elements Editor). A document must not contain more than 30 signing fields.
The full element model - placement modes (explicit coordinates, text markers, existing PDF form fields), dimensions, legal notices, and signing methods - is covered in the API reference for the element endpoints and in the field-positioning guide. This page covers only how elements fit into the package hierarchy.

​
The process

A package’s process defines who acts and when. It is an ordered list of process steps. Within a single step, the actors act in parallel; the steps themselves run in sequence. For example, a process might be:
  1. Approve (step 1)
  2. Fill in forms (step 1, alongside approval)
  3. Sign (step 2)
  4. Receive (step 3)
A few rules govern how steps can be arranged:
  • Form filling and approval come first. Adding approval or form-filling data after signatures are placed would invalidate those signatures, so FormFillers and Approvers must act before any signer. They are placed in the first step.
  • Receivers come last. A Receiver only gets the document once every signer has signed, so receivers are placed in the final step. The receiver step is always parallel.
  • One actor type per step, with one exception: FormFillers and Approvers may share a step. Mixing other actor types within a single step is not supported.
If you do not define the process steps manually, FormFillers are placed in the first step alongside Approvers - so approval may happen before, during, or after form filling. You can read the whole process, read or modify a single step by its index, add an actor to an existing step, or overwrite the entire process at once. See the process endpoints in the API reference for the specific calls.

​
ExternalReference

Most objects you create - packages, stakeholders, elements - accept an optional ExternalReference (maximum length 256). It is a free-form string that your calling application controls. The NSEV platform does not use it itself; it exists so you can correlate API objects with records in your own system (for instance, storing your internal case ID on the package). ExternalReference also surfaces in redirect flows. When a Signer or FormFiller actor finishes and is redirected to a RedirectUrl, the platform appends query parameters to that URL, including the stakeholder’s ExternalReference (as ExternalReference) and the package’s ExternalReference (as PackageExternalReference). Setting meaningful external references therefore lets your return endpoint identify which package and stakeholder a returning user belongs to.
A RedirectUrl return is client-side and can be tampered with by the end user. Do not trust the appended Status alone - confirm completion out of band by calling GET /packages/{packageId}/status or by using a server-side callback.

​
Additional properties

Person stakeholders and group members can carry AdditionalProperties: extra fields configured in your tenant’s Contact Properties Settings, holding any stakeholder information your administrator requires (for example a national ID or a nationality). Two properties are configured by default in every environment: BeId (a national security number) and BeLawyer (a lawyer ID). When a mandated signing rule is applied to an additional property, that property becomes mandatory: its value is checked against the data extracted from the signing certificate or returned by the signing service, and the stakeholder is only mandated to sign when the data matches. To see which additional properties are mandatory for a given signing method, call GET /signingmethods.

​
Putting it together

To prepare a single-signer package end to end you would: create the package, upload a document, add a Person stakeholder, create a Signer actor on that stakeholder with a signing field element placed on the document, and then activate the package. The Send a document for signing tutorial walks through exactly that flow with full request examples.