Get package

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "BatchId": "00000000-0000-0000-0000-000000000000",
  "Name": "example package",
  "Status": "Draft",
  "IsActionNeeded": true,
  "CreationDate": "2023-11-07T05:31:56Z",
  "ExpiryDate": "2023-11-07T05:31:56Z",
  "RevocationDate": "2023-11-07T05:31:56Z",
  "Initiator": "hello@world.test",
  "UnplacedElements": [
    {
      "Type": "signingField",
      "SigningMethods": [
        "manual"
      ],
      "LegalNotice": {
        "Text": "read and approved"
      },
      "Id": "C923F37A-DD9F-4877-B81C-40F2940C51B0",
      "ActorId": "4F2C1AED-DAE3-44F5-9879-0E3FFF9ED0B8",
      "Status": "Pending",
      "ExternalReference": "external reference example",
      "MarkerType": "PdfFormField",
      "MarkerId": "#SIG01"
    }
  ],
  "Documents": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "PackageId": "00000000-0000-0000-0000-000000000000",
      "Name": "example document",
      "CreationDate": "2023-11-07T05:31:56Z",
      "MediaType": "application/pdf",
      "Language": "en",
      "Status": "Draft",
      "Elements": [
        {
          "Type": "SigningField",
          "Id": "00000000-0000-0000-0000-000000000000",
          "ActorId": "00000000-0000-0000-0000-000000000000",
          "Status": "Pending",
          "ExternalReference": "<string>",
          "CompletedDate": "<string>",
          "Location": {
            "Page": 2,
            "Top": 200,
            "Left": 200
          },
          "UsedSigningMethod": "<string>",
          "SigningMethods": [
            "manual"
          ],
          "KeyPairMappings": [
            {
              "SigningMethodName": "MailOtp:MailOtp",
              "KeyPair": "MyKeyPair"
            }
          ],
          "LegalNotice": {
            "Text": "Read and approved"
          },
          "Dimensions": {
            "Width": 200,
            "Height": 200
          }
        }
      ],
      "ExternalReference": "<string>",
      "ProofCorrelationId": "<string>",
      "OrderIndex": 123,
      "IsActionNeeded": true,
      "ErrorCode": "<string>",
      "HasSignatures": true,
      "HasSigningFields": true,
      "HasFormFields": true
    }
  ],
  "Stakeholders": [
    {
      "Type": "Undecided",
      "Id": "00000000-0000-0000-0000-000000000000",
      "PackageId": "00000000-0000-0000-0000-000000000000",
      "Actors": [
        {
          "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>"
    }
  ],
  "DefaultLegalNotice": {
    "Text": "Read and approved"
  },
  "ExternalReference": "<string>",
  "DocumentGroupCode": "<string>",
  "ThemeCode": "<string>",
  "CallBackUrl": "<string>",
  "NotificationCallBackUrl": "<string>",
  "F2fSigningUrl": "<string>",
  "PreviewUrl": "<string>",
  "DefaultRedirectUrl": "<string>",
  "F2fRedirectUrl": "<string>",
  "IsUnsignedContentDownloadable": true,
  "IsReassignEnabled": true,
  "ActionUrlExpirationPeriodInDays": 2,
  "ProofCorrelationId": "<string>",
  "AddInitiatorAsReceiver": true,
  "MustBeArchived": true,
  "ArchiveAuditProofs": true,
  "ArchiveAuditTrail": true,
  "Warnings": [
    {
      "ResourceType": "process",
      "Code": "ContactGroup.SomeMissingPhoneNumbers",
      "Message": "Some of the group members don't have a phone number required for [SmsOTP] signing type.",
      "Stakeholder": {
        "Id": "82c6b4f4-70fe-4fff-b176-6df0f4e79293",
        "ExternalReference": "userXYZ"
      },
      "Actor": {
        "Id": "73462bf5-8430-411d-befb-b35c92f35e10"
      }
    }
  ],
  "AutomaticReminder": {
    "IsSendAutomaticRemindersEnabled": true,
    "DaysBeforeFirstReminder": 2,
    "IsRepeatRemindersEnabled": true,
    "RepeatReminders": 2
  },
  "ExpirationReminder": {
    "IsSendExpirationRemindersEnabled": true,
    "DaysBeforeExpirationReminder": 2
  },
  "OtpAuthenticationSetting": {
    "IsSmsOtpAuthenticationEnabled": true,
    "IsMailOtpAuthenticationEnabled": true
  },
  "DefaultSigningMethods": [
    {
      "Name": "MailOtp:MailOtp",
      "KeyPair": "MyKeyPair"
    }
  ]
}

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

GET

packages

{packageId}

Error

A valid request URL is required to generate request examples

{
  "Id": "00000000-0000-0000-0000-000000000000",
  "BatchId": "00000000-0000-0000-0000-000000000000",
  "Name": "example package",
  "Status": "Draft",
  "IsActionNeeded": true,
  "CreationDate": "2023-11-07T05:31:56Z",
  "ExpiryDate": "2023-11-07T05:31:56Z",
  "RevocationDate": "2023-11-07T05:31:56Z",
  "Initiator": "hello@world.test",
  "UnplacedElements": [
    {
      "Type": "signingField",
      "SigningMethods": [
        "manual"
      ],
      "LegalNotice": {
        "Text": "read and approved"
      },
      "Id": "C923F37A-DD9F-4877-B81C-40F2940C51B0",
      "ActorId": "4F2C1AED-DAE3-44F5-9879-0E3FFF9ED0B8",
      "Status": "Pending",
      "ExternalReference": "external reference example",
      "MarkerType": "PdfFormField",
      "MarkerId": "#SIG01"
    }
  ],
  "Documents": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "PackageId": "00000000-0000-0000-0000-000000000000",
      "Name": "example document",
      "CreationDate": "2023-11-07T05:31:56Z",
      "MediaType": "application/pdf",
      "Language": "en",
      "Status": "Draft",
      "Elements": [
        {
          "Type": "SigningField",
          "Id": "00000000-0000-0000-0000-000000000000",
          "ActorId": "00000000-0000-0000-0000-000000000000",
          "Status": "Pending",
          "ExternalReference": "<string>",
          "CompletedDate": "<string>",
          "Location": {
            "Page": 2,
            "Top": 200,
            "Left": 200
          },
          "UsedSigningMethod": "<string>",
          "SigningMethods": [
            "manual"
          ],
          "KeyPairMappings": [
            {
              "SigningMethodName": "MailOtp:MailOtp",
              "KeyPair": "MyKeyPair"
            }
          ],
          "LegalNotice": {
            "Text": "Read and approved"
          },
          "Dimensions": {
            "Width": 200,
            "Height": 200
          }
        }
      ],
      "ExternalReference": "<string>",
      "ProofCorrelationId": "<string>",
      "OrderIndex": 123,
      "IsActionNeeded": true,
      "ErrorCode": "<string>",
      "HasSignatures": true,
      "HasSigningFields": true,
      "HasFormFields": true
    }
  ],
  "Stakeholders": [
    {
      "Type": "Undecided",
      "Id": "00000000-0000-0000-0000-000000000000",
      "PackageId": "00000000-0000-0000-0000-000000000000",
      "Actors": [
        {
          "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>"
    }
  ],
  "DefaultLegalNotice": {
    "Text": "Read and approved"
  },
  "ExternalReference": "<string>",
  "DocumentGroupCode": "<string>",
  "ThemeCode": "<string>",
  "CallBackUrl": "<string>",
  "NotificationCallBackUrl": "<string>",
  "F2fSigningUrl": "<string>",
  "PreviewUrl": "<string>",
  "DefaultRedirectUrl": "<string>",
  "F2fRedirectUrl": "<string>",
  "IsUnsignedContentDownloadable": true,
  "IsReassignEnabled": true,
  "ActionUrlExpirationPeriodInDays": 2,
  "ProofCorrelationId": "<string>",
  "AddInitiatorAsReceiver": true,
  "MustBeArchived": true,
  "ArchiveAuditProofs": true,
  "ArchiveAuditTrail": true,
  "Warnings": [
    {
      "ResourceType": "process",
      "Code": "ContactGroup.SomeMissingPhoneNumbers",
      "Message": "Some of the group members don't have a phone number required for [SmsOTP] signing type.",
      "Stakeholder": {
        "Id": "82c6b4f4-70fe-4fff-b176-6df0f4e79293",
        "ExternalReference": "userXYZ"
      },
      "Actor": {
        "Id": "73462bf5-8430-411d-befb-b35c92f35e10"
      }
    }
  ],
  "AutomaticReminder": {
    "IsSendAutomaticRemindersEnabled": true,
    "DaysBeforeFirstReminder": 2,
    "IsRepeatRemindersEnabled": true,
    "RepeatReminders": 2
  },
  "ExpirationReminder": {
    "IsSendExpirationRemindersEnabled": true,
    "DaysBeforeExpirationReminder": 2
  },
  "OtpAuthenticationSetting": {
    "IsSmsOtpAuthenticationEnabled": true,
    "IsMailOtpAuthenticationEnabled": true
  },
  "DefaultSigningMethods": [
    {
      "Name": "MailOtp:MailOtp",
      "KeyPair": "MyKeyPair"
    }
  ]
}

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

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"

Response

Package was found

Response model for a package

string<guid>

A package's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

BatchId

string<guid>

A batch's unique identifier, grouping multiple packages

Example:

"00000000-0000-0000-0000-000000000000"

Name

string

Name of the package. It is shown in the NSEV WebPortal and used as the file name when the package is downloaded as a .zip file, so do not add a file extension.

Avoid forbidden file-name characters - slash (/), backslash (\), question mark (?), percent (%), asterisk (*), colon (:), pipe (|), single quote, double quote ("), less-than (<) and greater-than (>) - and HTML-sensitive characters such as ampersand (&) and apostrophe. This list is not exhaustive. When using itsme signing, use only characters supported by ISO 8859-15; some software-generated characters such as curly apostrophes and long dashes are not supported.

Required string length: 1 - 150

Example:

"example package"

Status

enum<string>

The status of a package

Available options:

Draft,

Pending,

InProgress,

Ending,

Finished,

Archived,

Rejected,

Revoked,

Expired,

Failed,

Processing,

ProcessingFailed

IsActionNeeded

boolean

If present, the package contains not fully uploaded documents. Signatures/markers were detected and user must take an action to keep/remove them.

CreationDate

string<date-time>

When the resource was created

ExpiryDate

string<date-time>

When the resource will expire

RevocationDate

string<date-time> | null

Date and time in UTC when the package got revoked. Will only be present for packages that are revoked.

Initiator

string<email>

Email address of a known user of the webSigner portal

Example:

"hello@world.test"

UnplacedElements

(Unplaced signing field (result) · object | Unplaced check box field (result) · object | Unplaced text box field (result) · object | Unplaced radio group (result) · object | Unplaced combo box field (result) · object)[]

This package's elements that aren't placed aynywhere yet

A field that can be signed by an actor

Unplaced signing field (result)
Unplaced check box field (result)
Unplaced text box field (result)
Unplaced radio group (result)
Unplaced combo box field (result)

Show child attributes

Example:

{
  "Type": "signingField",
  "SigningMethods": ["manual"],
  "LegalNotice": { "Text": "read and approved" },
  "Id": "C923F37A-DD9F-4877-B81C-40F2940C51B0",
  "ActorId": "4F2C1AED-DAE3-44F5-9879-0E3FFF9ED0B8",
  "Status": "Pending",
  "ExternalReference": "external reference example",
  "MarkerType": "PdfFormField",
  "MarkerId": "#SIG01"
}

Documents

object[]

This package's documents

Show child attributes

Stakeholders

(Undecided stakeholder · object | Person stakeholder · object | Group stakeholder · object | Contact group stakeholder · object)[]

This package's stakeholders

Unspecified stakeholder

Undecided stakeholder
Person stakeholder
Group stakeholder
Contact group stakeholder

Show child attributes

DefaultLegalNotice

Custom legal notice text · object

The default legal notice that will be added to a signing field

Show child attributes

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

DocumentGroupCode

string

Identifier of the document group the package is uploaded to. By default an initiator uploads to their personal "My Documents" folder, which cannot be shared. An NSEV admin can configure additional document groups so users can collaborate on each other's packages. To use "My Documents", omit this parameter or pass 00001; to use a specific group, pass its document group code. Use the Get document groups call to discover the configured codes.

ThemeCode

string

identifier of the theme this package has

CallBackUrl

string<url>

url that will be called each time a signature has been put on the document

NotificationCallBackUrl

string<url>

url that will be called when the signer requests a new signing url

F2fSigningUrl

string<url>

Link to the package which allows to start a face to face signing session

PreviewUrl

string<url>

Link to the package which allows only a preview of documents

DefaultRedirectUrl

string<url>

Default url to which stakeholders will be redirected after completing their actions. Set on package submit, when actor has no RedirectUrl.

F2fRedirectUrl

string<url>

Url to which the end user is redirected after all fields have been signed with ‘face to face’ signing.

IsUnsignedContentDownloadable

boolean

Whether a signer can download the unsigned content of this package or not Default when not specified is taken from config ( Customization Settings > IsDownloadUnsignedFilesEnabled )

IsReassignEnabled

boolean

Whether a stakeholder can reassign his/her action ( actor ) to another party.
Default when not specified is taken from config ( Customization Settings > IsReassignEnabled )

ActionUrlExpirationPeriodInDays

integer | null

This parameter determines after how many days the action URLs must expire when they are not used. When no value is entered, this parameter takes its value from the Config Index setting IsActionUrlExpirationEnabled under Customization Settings. The maximum value equals the number of days left until 9999-12-31.

Required range: x >= 1

ProofCorrelationId

string

deprecated

Id for correlating with other resources in the proofs system

AddInitiatorAsReceiver

boolean | null

If true, adds the initiator as a receiver on submit. This property is only available on draft packages.

MustBeArchived

boolean

If true, the package will be sent to the external archive when status is FINISHED.

ArchiveAuditProofs

boolean

If true, the audit proofs will be sent to the external archive when package status is FINISHED.

ArchiveAuditTrail

boolean

If true, the audit trail will be sent to the external archive when package status is FINISHED.

Warnings

(Process warning · object | Package warning · object | Document warning · object)[]

A warning about the process of a package.
E.g. group members that don't have the necessary data to sign with a signing method

Process warning
Package warning
Document warning

Show child attributes

Example:

{
  "ResourceType": "process",
  "Code": "ContactGroup.SomeMissingPhoneNumbers",
  "Message": "Some of the group members don't have a phone number required for [SmsOTP] signing type.",
  "Stakeholder": {
    "Id": "82c6b4f4-70fe-4fff-b176-6df0f4e79293",
    "ExternalReference": "userXYZ"
  },
  "Actor": {
    "Id": "73462bf5-8430-411d-befb-b35c92f35e10"
  }
}

AutomaticReminder

object

Contains information about a package's automatic reminder settings. Please note that values are taken from configuration defaults, if request object is empty.

Show child attributes

ExpirationReminder

object

Contains information about a package's expiration reminder settings. Please note that values are taken from configuration defaults, if request object is empty.

Show child attributes

OtpAuthenticationSetting

object

Contains settings for the package OTP authentication

Show child attributes

DefaultSigningMethods

Signing method with key pair · object[] | null

Available as of NSEV v8.5. Default signing methods applied to every signing field that is created on the package without explicitly configured signing methods - whether at package or actor creation, through the create element endpoints, or from marker-matched fields at document upload. Only populated while the package is a draft: the defaults are copied onto each such field the moment it is created, and on submit this package-level property is cleared. Not exposed on the template object itself, but a package created from a template inherits the source package's defaults.

Show child attributes

Product updates

NSEV WebPortal API

Authorizations

Path Parameters

Response