Actors

Create actor

Creates an actor and adds it to the specified stakeholder. An actor is a single action a stakeholder must take on a package. There are four actor types, selected with the Type property:

FormFiller - fills in TextBoxField, CheckBoxField, RadioGroup and/or ComboBoxField (available as of NSEV v8.5) elements on a document. Does not sign or approve.
Approver - approves the document before it is sent to any signer. Approval may happen before or after form filling, as long as both come before signing.
Signer - signs the document.
Receiver - receives a copy of the document once all signers have signed. Takes no action on the document.

The request parameters are the same for all four types except for Elements: SigningField elements can only be linked to Signers, and TextBoxField, CheckBoxField, RadioGroup and ComboBoxField elements can only be linked to FormFillers. Receivers cannot have elements. The element parameters are the same as for Create element.

Where an actor sits in the process matters: FormFillers and Approvers must be in the first process step (they act before signing), and Receivers must be in the last step (they receive only after all signers finish). 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. A single process step may only contain one actor type, except that FormFillers and Approvers may be mixed within one step.

RedirectUrl behaviour. When RedirectUrl is set, the end user is redirected to that URL after filling forms, signing or rejecting; without it, the user must close the browser tab manually. The URL must be a valid absolute URL with no existing query parameters - NSEV appends SessionID (the ActorId), ExternalReference (the stakeholder’s external reference), Status (FINISHED, REJECTED or INVALIDTOKEN) and PackageExternalReference (the package’s external reference) as query parameters. Because the redirect happens client-side the end user can counterfeit it, so confirm completion out of band - via a callback or by calling Get package status - rather than trusting the redirect alone. RedirectType controls when the redirect fires; see its property description.

POST

packages

{packageId}

stakeholders

{stakeholderId}

actors

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "Type": "signer",
  "Status": "available",
  "SuppressNotifications": false
}

[
  {
    "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"

stakeholderId

string<guid>

required

The target stakeholder's unique identifier A stakeholder's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Body

application/json

Signer
Approver
Form filler
Receiver

Signs one or more signing fields

Type

enum<string>

required

The type of action an actor performs on a package, and the discriminator across the actor variants.

FormFiller - fills TextBoxField, CheckBoxField, RadioGroup and ComboBoxField (NSEV v8.5+) elements; does not sign or approve. Must be placed in the first process step.
Approver - approves a document as fit for signing, before any signer acts. Must be placed in the first process step (may share it with FormFillers).
Signer - signs one or more signing fields.
Receiver - receives a copy of the fully signed document; takes no action and must be placed in the last process step.

Available options:

Signer

SuppressNotifications

boolean

default:false

suppress the notifications for this actor

RedirectUrl

string<url>

Url to which the stakeholder is redirected after completing this action

Elements

(New signing field on a document · object | Existing element by Id · object)[]

The actor's elements

Parameters for creating a signing field

New signing field on a document
Existing element by Id

Show child attributes

RedirectType

enum<string>

When stakeholder gets redirected after completing this action

afterSession - Redirect after signing session is ended, but before package is completed (only important for last signer).
immediately - Redirect as soon as possible.
afterDelay - Redirect after some delay (defined on frontend).
afterCompletion - Redirect after the package is completed.

Only valid together with RedirectUrl - the API rejects RedirectType without it.

Available options:

AfterSession,

Immediately,

AfterDelay,

AfterCompletion

BackButtonUrl

string<url>

URL to which the end user is sent after pressing close session button

Example:

"https://homepage.example.test"

Response

Actor was created

Signer
Approver
Receiver
Form filler

Signs one or more signing fields

string<guid>

This actor's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Type

enum<string>

The type of action an actor performs on a package, and the discriminator across the actor variants.

FormFiller - fills TextBoxField, CheckBoxField, RadioGroup and ComboBoxField (NSEV v8.5+) elements; does not sign or approve. Must be placed in the first process step.
Approver - approves a document as fit for signing, before any signer acts. Must be placed in the first process step (may share it with FormFillers).
Signer - signs one or more signing fields.
Receiver - receives a copy of the fully signed document; takes no action and must be placed in the last process step.

Available options:

Signer

Status

enum<string>

The status of an actor's action.

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/signers).

Available options:

Draft,

Waiting,

Available,

InProgress,

Failed,

Finished,

Rejected,

Skipped

SuppressNotifications

boolean

default:false

suppress the notifications for this actor

ActionUrls

object[]

Show child attributes

Links

string<url>[]

Only present when the actor's stakeholder is a person.

links to interact with the package for this person stakeholder

MemberLinks

object[]

Only present when the actor's stakeholder is a group or contact group.

Show child attributes

Result

object

The result of a completed action

Show child attributes

Elements

Signing field · object[]

The actor's elements

Show child attributes

RedirectUrl

string<url>

Url to which the stakeholder is redirected after completing this action

RedirectType

enum<string>

When stakeholder gets redirected after completing this action

afterSession - Redirect after signing session is ended, but before package is completed (only important for last signer).
immediately - Redirect as soon as possible.
afterDelay - Redirect after some delay (defined on frontend).
afterCompletion - Redirect after the package is completed.

Only valid together with RedirectUrl - the API rejects RedirectType without it.

Available options:

AfterSession,

Immediately,

AfterDelay,

AfterCompletion

BackButtonUrl

string<url>

URL to which the end user is sent after pressing close session button

Example:

"https://homepage.example.test"

Get actorRetrieves a single actor by its actor ID.

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "Type": "signer",
  "Status": "available",
  "SuppressNotifications": false
}

[
  {
    "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 actor

Authorizations

Path Parameters

Body

Response