Instant package

This tutorial shows the quickest way to get a document signed with the NSEV WebPortal API: a single super call that creates the package and everything inside it at once, activated immediately so the signer can act. After the call you only poll for completion and download the result. If you are building a real integration, the step-by-step flow in Send a document for signing is usually a better fit - it gives you each object’s Id as you go and is easier to handle errors against. This page is for when you already know exactly what the package should contain and want the fewest possible requests.

Prerequisites

A valid access token or Basic Auth credentials - see Platform Access
Your tenant’s base URL set as BASE_URL
A PDF document to upload (max 30 MB)

All examples use Bearer authentication. Replace the token and variable values with your own.

How the super call works

A super call combines into one POST /packages request everything the step-by-step flow does across six calls: the package, its documents, the stakeholders, their actors, the placed elements, and the process order. Setting Status to pending in the same body activates the package immediately, so no separate activation call is needed. There is one concept that only appears in the super call. When you add a document with its own call you get back a document Id and reference it when placing a signing field. In a super call the documents do not exist yet, so there are no IDs to reference. Instead, each element points at its target document by position using DocumentIndex: 0 is the first document in the call, 1 the second, and so on.

A super call cannot be combined with a template. To create a package from a template, pass a TemplateCode instead of inlining documents and stakeholders; the package then inherits everything defined in the template. See Templates → Templates and super calls.

Step 1: Create everything in one call

The request below creates a package named Employment Contract, uploads one base64-encoded PDF, adds Jane Smith as a person stakeholder with a Signer actor, places one signing field on the first document, and activates the package - all at once. Encode your PDF:

# Linux
export DOC_BASE64=$(base64 -w 0 contract.pdf)

# macOS
export DOC_BASE64=$(base64 -i contract.pdf | tr -d '\n')

Make the super call:

curl -X POST "$BASE_URL/packages" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d "{
    \"Name\": \"Employment Contract\",
    \"Initiator\": \"sender@yourcompany.com\",
    \"Status\": \"Pending\",
    \"Documents\": [
      {
        \"Name\": \"Employment Contract\",
        \"Language\": \"en\",
        \"DocumentOptions\": {
          \"ContentType\": \"application/pdf\",
          \"TargetType\": \"application/pdf\",
          \"PdfOptions\": {
            \"TargetFormat\": \"pdf\",
            \"PdfErrorHandling\": \"DetectFixWarn\"
          },
          \"Base64data\": \"$DOC_BASE64\"
        }
      }
    ],
    \"Stakeholders\": [
      {
        \"Type\": \"Person\",
        \"Language\": \"en\",
        \"FirstName\": \"Jane\",
        \"LastName\": \"Smith\",
        \"EmailAddress\": \"jane.smith@example.com\",
        \"BirthDate\": \"1985-04-12\",
        \"Actors\": [
          {
            \"Type\": \"Signer\",
            \"ProcessStep\": 0,
            \"Elements\": [
              {
                \"Type\": \"SigningField\",
                \"DocumentIndex\": 0,
                \"SigningMethods\": [\"manual:manual\"],
                \"Location\": {
                  \"Page\": 1,
                  \"Top\": 600,
                  \"Left\": 100
                },
                \"Dimensions\": {
                  \"Width\": 200,
                  \"Height\": 70
                }
              }
            ]
          }
        ]
      }
    ]
  }"

Because Status is Pending, the package is created and activated in one step, and Jane receives an email notification with a link to sign. Save the Id from the response - you need it to poll and download.

{
  "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Name": "Employment Contract",
  "Initiator": "sender@yourcompany.com",
  "Status": "Pending",
  "Documents": [
    {
      "Id": "1e501b99-9f0f-4f12-9ad9-6c737c6394e8",
      "Name": "Employment Contract",
      "Language": "en"
    }
  ],
  "Stakeholders": [
    {
      "Id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "Type": "Person",
      "FirstName": "Jane",
      "LastName": "Smith",
      "EmailAddress": "jane.smith@example.com",
      "Actors": [
        {
          "Id": "5d197888-8660-4374-bb42-102a4f6e35c4",
          "Type": "Signer"
        }
      ]
    }
  ]
}

export PACKAGE_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

The signing element coordinates are in points (1 point = 1/72 inch) from the top-left of the page. Adjust Page, Top, and Left to position the signature field where you want it on your document. A signing field must be at least 50 × 30 points.

A package must not exceed 150 MB in total and should not contain more than 15 documents, with each document no larger than 30 MB. An .xml document must not exceed 2 million characters, and a package must not contain more than 15 .xml files.

SigningMethods references the methods configured for your tenant (for example, manual:manual or smartcard:beid). The names are case-sensitive. Call GET /signingmethods to list the methods available to you and use the returned Name values here.

Step 2: Monitor status

Poll GET /packages/{packageId}/status until the package is Finished:

curl "$BASE_URL/packages/$PACKAGE_ID/status" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0"

The package moves through the following statuses:

Status	Meaning
`Pending`	Package is activated, waiting for the first signer
`Finished`	Signing complete - documents are ready to download
`Rejected`	A signer rejected the package
`Revoked`	Package was cancelled
`Expired`	Package exceeded its expiry date without being completed
`Failed`	Processing failed - the package cannot be completed

Polling is the simplest way to detect completion, but for production integrations a status-change callback is more efficient than repeated requests. Set a CallBackUrl on the package and let NSEV notify you instead - see Callbacks and redirects.

Step 3: Download the signed document

Once the status is Finished, download the signed documents as a .zip file:

curl "$BASE_URL/packages/$PACKAGE_ID/download" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0" \
  -o signed-package.zip

Only Finished and Archived packages can be downloaded; downloading a package in any other state returns 409 Conflict.

Next steps

Build packages step by step, with an Id returned at each stage, in Send a document for signing
Understand how documents, stakeholders, actors, and elements relate in The package model
Replace polling with status-change callbacks in Callbacks and redirects
Review Best Practices for error handling, pagination, and security

Concepts

Tutorials

Guides

Prerequisites

How the super call works

Step 1: Create everything in one call

Step 2: Monitor status

Step 3: Download the signed document

Next steps

​Prerequisites

​How the super call works

​Step 1: Create everything in one call

​Step 2: Monitor status

​Step 3: Download the signed document

​Next steps

Prerequisites

How the super call works

Step 1: Create everything in one call

Step 2: Monitor status

Step 3: Download the signed document

Next steps