Documents

Add document

Adds a document to an existing package. After the document is added you can build it out further by adding elements (signing fields, checkbox fields, text box fields and radio groups) in separate calls, or you can supply everything in this single call by including the Elements array.

Documents can be added synchronously or asynchronously, selected with the async query parameter:

Synchronous (async=false, the default): the call blocks until the document has been uploaded and processed, then returns 201 Created with the created document.
Asynchronous (async=true): the call returns 202 Accepted immediately with a Location header pointing at the package, and the document is processed in the background. Poll the package (Get package by ID) until its status is Draft before continuing to work on it. Asynchronous upload also enables the KeepSignatures, KeepSigningFields and KeepFormFields options under DocumentOptions, which let you preserve signatures and detected field markers found in the uploaded file.

A document can also be marked optional. Optional documents let a package mix mandatory and optional documents; end users may then choose not to fill in or sign the optional ones while still completing the mandatory ones.

The request accepts either application/json (with the file supplied as Base64 in DocumentOptions.Base64data) or multipart/form-data (with the file attached as the Document part and an optional Representation part). The multipart form takes the same parameters as the JSON body except that ContentType and Base64data are not used - the file is the attached part instead.

Package size and content limits:

A package must not exceed 150 MB.
A package must not contain more than 15 documents, and each document must not exceed 30 MB.
An XML file must not contain more than 2 million characters, and a package must not contain more than 15 XML files.
A PDF document’s physical dimensions must not exceed 3.99 m by 3.99 m.
A package cannot contain both XML documents and PDF documents on which signatures will be placed. The package type is determined by the first uploaded document.
Large files may slow signing depending on the end user’s connection.

PDF handling notes:

PDF/A uploads are only allowed when the format is pdfa1a or pdfa2a. Adding form fields to a PDF/A document breaks the “/A” conformance, leaving a regular PDF; to recover PDF/A, set DocumentOptions.PdfOptions.TargetFormat to pdfa1a or pdfa2a so the document is reconverted after all fields are filled or saved.
Rotated PDFs should not be combined with text markers: detected signature locations are not rotated to match the text direction and are placed near the marker on a best-effort basis.
When an uploaded PDF contains text fields whose name matches the configured Text Field format, those fields are converted to empty signature fields and the original text field is not displayed. This does not apply to documents that already contain one or more signatures.
Signature and text field names in uploaded PDFs must contain only letters and numbers; special characters such as accented letters, slashes and dots are not supported.

PDF error handling is controlled by DocumentOptions.PdfOptions.PdfErrorHandling. Some PDFs have minor flaws that prevent signing; depending on this value and the server configuration, PDFs are checked and optionally fixed. A PDF that already contains signatures is never fixed, because fixing it would invalidate those signatures. See the property description for the meaning of each value.

POST

packages

{packageId}

documents

Error

A valid request URL is required to generate request examples

{
  "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",
  "Elements": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "ActorId": "00000000-0000-0000-0000-000000000000",
      "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
}

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

Query Parameters

async

boolean

default:false

This parameter allows to upload and process the document asynchronously. If set to true the location header will contain a uri that allows to monitor the process.

Body

Parameters for creating a document

Name

string

required

Name of the document, displayed in the WebPortal. Do not include a file extension. The name must not contain special characters such as slash, backslash, question mark, percent, asterisk, colon, pipe, single quote, double quote, less-than or greater-than. When itsme is used as a signing method, restrict the name to 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

Language

string<languageCode>

required

Language used in signature texts and in legal notices when an actor's LegalNoticeCode is set. Supported values: en, nl, de, fr, es, da, nb, sv, fi, lv, pl, hu, it, pt, ro.

Example:

"en"

DocumentOptions

object

required

Contains a document's base64 data and media type

Show child attributes

IsOptional

boolean

default:false

Determines whether the document is optional. Default value is false. When set to true, actors may choose not to form fill/sign the document.

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

Elements

(Place an unplaced element · object | Signing field · object | Check box field · object | Text box field · object | Radio group · object)[]

A list of elements (that aren't linked to an actor at once) on the created document

Parameters for placing an existing unplaced element, identified by UnplacedElementId. Choose one placement method and supply only its fields:

Explicit coordinates - supply Location and Dimensions.
Text marker - supply Marker (a code embedded in the document text).
Radio group - supply Options, each button positioned by its own Location and Dimensions (used when the unplaced element is a radio group, instead of Location/Marker).

Do not combine methods. For the full rules and marker formats see the Field positioning guide.

Place an unplaced element
Signing field
Check box field
Text box field
Radio group

Show child attributes

Example:

{
  "Location": { "Page": 2, "Top": 200, "Left": 200 },
  "Dimensions": { "Width": 200, "Height": 200 }
}

ProofCorrelationId

string

deprecated

Id for correlating this document with other resources in the proofs system

RepresentationOptions

object

Contains a document's base64 data and media type

Show child attributes

Response

Document was created

A single document

string<guid>

A document's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

PackageId

string<guid>

A package's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Name

string

Name of the document

Required string length: 1 - 150

Example:

"example document"

CreationDate

string<date-time>

When the resource was created

MediaType

enum<string>

The media type of a file

Available options:

application/pdf,

application/xml

Example:

"application/pdf"

Language

string<languageCode>

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

Example:

"en"

Status

enum<string>

The status of a document

Available options:

Draft,

Pending,

InProgress,

Ending,

Finished,

Rejected,

Revoked,

Expired,

Failed,

Processing,

ProcessingFailed

Elements

(Signing field · object | Check box field · object | Text box field · object | Radio group · object)[]

The document's elements

A field that can be signed by an actor

Signing field
Check box field
Text box field
Radio group

Show child attributes

ExternalReference

string

Maximum string length: 256

ProofCorrelationId

string

deprecated

Id for correlating with other resources in the proofs system

OrderIndex

integer

The Order Index of the document.

Get documentRetrieves a single document from a package by its document ID.

Error

A valid request URL is required to generate request examples

{
  "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",
  "Elements": [
    {
      "Id": "00000000-0000-0000-0000-000000000000",
      "ActorId": "00000000-0000-0000-0000-000000000000",
      "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
}

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

Add document

Authorizations

Path Parameters

Query Parameters

Body

Response