> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The package model

> How a package is structured in Nitro Sign Enterprise Verified: documents, stakeholders, actors, elements, and the process that orders them.

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.

```
Package
├── Documents
│     └── Elements          (signing fields, form fields placed on a page)
├── Stakeholders
│     └── Actors            (signer, approver, form filler, receiver)
└── Process
      └── Process steps     (each step = actors acting in parallel; steps run in sequence)
```

<Note>
  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](/docs/nsev/build/guides/good-practices) for the
  required order of these steps.
</Note>

## 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:

<Columns cols={3}>
  <Card title="Person" icon="user">
    A single individual. Only that person can act on the package.
  </Card>

  <Card title="Group" icon="users">
    A group of people, defined inline through `Members`. Any one member can act on behalf of the
    whole group.
  </Card>

  <Card title="ContactGroup" icon="address-book">
    References a contact group already created in the WebPortal, by its `ContactGroupCode`,
    instead of listing members inline.
  </Card>
</Columns>

**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.

<Note>
  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.
</Note>

## 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:

| Type           | What it does                                                                               | Works with elements                     |
| -------------- | ------------------------------------------------------------------------------------------ | --------------------------------------- |
| **FormFiller** | Fills in text boxes, checkboxes, and radio groups on a document. Does not sign or approve. | TextBoxField, CheckBoxField, RadioGroup |
| **Approver**   | Approves the document as fit for signing, before any signer acts.                          | None                                    |
| **Signer**     | Signs one or more signing fields.                                                          | SigningField                            |
| **Receiver**   | Receives a copy of the fully signed document. Takes no action.                             | None                                    |

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:

| Status       | Meaning                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `Draft`      | The package is still in draft; the action is not yet active.             |
| `Waiting`    | The action is waiting for an earlier process step to complete.           |
| `Available`  | The action is ready to be performed.                                     |
| `InProgress` | The action is being performed.                                           |
| `Failed`     | The action failed.                                                       |
| `Finished`   | The action was completed.                                                |
| `Rejected`   | The actor rejected the document.                                         |
| `Skipped`    | The action was skipped (for example via skip approvers or skip signers). |

### 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](#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.

<Note>
  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.
</Note>

## 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.

<Warning>
  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.
</Warning>

## 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](/docs/nsev/build/tutorials/send-for-signing) tutorial walks through exactly that
flow with full request examples.