Stakeholders

Create stakeholder

Creates a stakeholder and adds it to the specified package. A stakeholder is an entity that has an interest in a package; a single stakeholder may carry multiple actors (the actions it must take, such as filling forms, approving, signing or receiving).

Three types of stakeholder can be created, selected with the Type property:

person - a single individual. Only that person can act on the package.
group - a group of people, defined inline through Members. Any member can form fill, approve or sign on behalf of the whole group, and each member receives a unique URL. As soon as one member acts, the others can no longer act.
contactGroup - references a contact group already created in the NSEV WebPortal by its ContactGroupCode, instead of listing members inline. It behaves like a group stakeholder. A contactGroup stakeholder only exists while the package is in draft; once the package moves to pending it is converted to a group stakeholder, while the contact group code is retained.

Actors can be supplied inline through Actors. The actor parameters are the same as for Create actor.

POST

packages

{packageId}

stakeholders

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "PackageId": "00000000-0000-0000-0000-000000000000",
  "Type": "group",
  "Actors": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "signer",
      "Status": "available",
      "MemberLinks": [
        {
          "Email": "zu@li.test",
          "Link": "https://dothething.test"
        },
        {
          "Email": "john@doe.test",
          "Link": "https://alsocompleteyouraction.test"
        }
      ]
    }
  ],
  "GroupName": "string",
  "Members": [
    {
      "Language": "en",
      "FirstName": "John",
      "LastName": "Doe",
      "EmailAddress": "john@doe.test",
      "BirthDate": "1990-01-16"
    },
    {
      "Language": "en",
      "FirstName": "Zu",
      "LastName": "Li",
      "EmailAddress": "zu@li.test",
      "BirthDate": "1991-03-14",
      "AdditionalProperties": {
        "BeId": "12345678900",
        "BeLawyer": "b459d74c-1f90-4d63-9f4a-6de9cead8c5e"
      }
    }
  ]
}

[
  {
    "ErrorCode": "Name.MinimumLength:6",
    "ErrorMessage": "The minimum length for a name is 6"
  }
]

[
  {
    "ErrorCode": "Package.NotFound:00000000-0000-0000-0000-000000000000",
    "ErrorMessage": "The package with id '00000000-0000-0000-0000-000000000000' could not be found"
  }
]

[
  {
    "ErrorCode": "Something.WentWrong",
    "ErrorMessage": "Something went wrong"
  }
]

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

packageId

string<guid>

required

The target package's unique identifier A package's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Body

application/json

Parameters for creating a stakeholder

Person stakeholder
Group stakeholder
Contact group stakeholder

Parameters for creating a stakeholder

Type

enum<string>

required

The type of stakeholder, and the discriminator across the stakeholder variants.

Person - a single individual; only that person can act.
Group - a group of people defined inline; any member may act on behalf of the group, and once one member acts the others cannot.
ContactGroup - references a contact group created in the WebPortal by its code; behaves like a group. Exists only while the package is in draft and is converted to Group when the package moves to pending.
Undecided - the implicit stakeholder a package starts with before any stakeholder has been assigned; it cannot be deleted.

Available options:

Person

Language

string<languageCode>

required

A country's 2 letter ISO code (ISO 639-1)

Example:

"en"

LastName

string

required

Last name of the stakeholder

Maximum string length: 150

EmailAddress

string<email>

required

Example:

"hello@world.test"

ExternalReference

string

External reference to this resource set by the calling application. NSEV does not use this value itself. When filtering packages, this matches the package-level external reference only, not document or field references.

Maximum string length: 256

FirstName

string

First name of the stakeholder

Maximum string length: 150

BirthDate

string<date>

Date of birth in YYYY-MM-DD format. Activating mandated signer validation in the configuration may make this parameter effectively required.

PhoneNumber

string

Phone number used to receive an SMS OTP. Always include the country code (for example +32xxxxxxxxx); use a leading plus sign rather than "00" as the international dialing prefix, and never include spaces.

Example:

"+32xxxxxxxxx"

AdditionalProperties

object

Additional stakeholder properties configured in the Contact Properties Settings of the configuration - any extra stakeholder information the administrator requires (for example maiden name or nationality). Two properties are configured by default in every environment: BeId (the stakeholder's national security number) and BeLawyer (their lawyer ID). When a mandated signing rule is applied to a property, that property becomes mandatory and its value is checked against the data extracted from the signing certificate or returned by the signing service; a match is required for the stakeholder to be mandated to sign. Use Get signing methods to see which additional properties are mandatory for each signing method.

Show child attributes

Example:

{
  "BeId": "12345678900",
  "BeLawyer": "b459d74c-1f90-4d63-9f4a-6de9cead8c5e"
}

Actors

(Signer · object | Approver · object | Form filler · object | Receiver · object)[]

The actions to be performed ( a list of actors )

Signs one or more signing fields

Signer
Approver
Form filler
Receiver

Show child attributes

Example:

{
  "Type": "signer",
  "SuppressNotifications": false,
  "Elements": [
    {
      "Id": "5a5365e1-3780-47c7-9657-a1496be6ea5e"
    },
    {
      "Type": "signingField",
      "DocumentId": "c05866bc-6b5a-4b5b-a4c1-b76895469f6f",
      "Location": { "Page": 2, "Top": 200, "Left": 200 },
      "Dimensions": { "Width": 200, "Height": 200 }
    }
  ]
}

Response

Stakeholder was created

Undecided stakeholder
Person stakeholder
Group stakeholder
Contact group stakeholder

Unspecified stakeholder

Type

enum<string>

required

The type of stakeholder

Available options:

Undecided

string<guid>

A stakeholder's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

PackageId

string<guid>

A package's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Actors

(Signer · object | Receiver · object | Approver · object | Form filler · object)[]

The actions to be performed

Signs one or more signing fields

Signer
Receiver
Approver
Form filler

Show child attributes

Example:

{
  "Type": "signer",
  "Status": "available",
  "Elements": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "signingField",
      "Location": { "Page": 2, "Top": 250, "Left": 250 },
      "Dimensions": { "Width": 230, "Height": 230 }
    }
  ]
}

ExternalReference

string

Maximum string length: 256

Get stakeholderRetrieves a single stakeholder from a package by its stakeholder ID.

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "PackageId": "00000000-0000-0000-0000-000000000000",
  "Type": "group",
  "Actors": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "Type": "signer",
      "Status": "available",
      "MemberLinks": [
        {
          "Email": "zu@li.test",
          "Link": "https://dothething.test"
        },
        {
          "Email": "john@doe.test",
          "Link": "https://alsocompleteyouraction.test"
        }
      ]
    }
  ],
  "GroupName": "string",
  "Members": [
    {
      "Language": "en",
      "FirstName": "John",
      "LastName": "Doe",
      "EmailAddress": "john@doe.test",
      "BirthDate": "1990-01-16"
    },
    {
      "Language": "en",
      "FirstName": "Zu",
      "LastName": "Li",
      "EmailAddress": "zu@li.test",
      "BirthDate": "1991-03-14",
      "AdditionalProperties": {
        "BeId": "12345678900",
        "BeLawyer": "b459d74c-1f90-4d63-9f4a-6de9cead8c5e"
      }
    }
  ]
}

[
  {
    "ErrorCode": "Name.MinimumLength:6",
    "ErrorMessage": "The minimum length for a name is 6"
  }
]

[
  {
    "ErrorCode": "Package.NotFound:00000000-0000-0000-0000-000000000000",
    "ErrorMessage": "The package with id '00000000-0000-0000-0000-000000000000' could not be found"
  }
]

[
  {
    "ErrorCode": "Something.WentWrong",
    "ErrorMessage": "Something went wrong"
  }
]

Product updates

NSEV WebPortal API

Create stakeholder

Authorizations

Path Parameters

Body

Response