Elements

Create element

Adds one element to an existing document. The element type is chosen with the Type field, which can be one of four values:

SigningField - marks where a signature must be placed. Signing fields are always mandatory.
TextBoxField - a text input the end user can fill in. May carry a prefilled default value and may be mandatory or optional.
CheckBoxField - a checkbox the end user can toggle. May be checked by default and may be mandatory or optional.
RadioGroup - a group of radio buttons (the individual buttons are the group’s Options). May have a button selected by default and may be mandatory or optional.

An element is positioned in one of the ways described on the placement schemas: with an explicit Location and Dimensions, with a text Marker, or with a FieldId that references an existing form field in the uploaded document. A signing field signed only with the server signing method can also be created invisible, with no position at all. An element can instead be created from an existing unplaced element by supplying its UnplacedElementId.

A single document must not contain more than 30 signing fields.

When the request references a marker or an existing form field (Marker or FieldId), it is recommended to add the element at document-upload time: after a document conversion the referenced marker or field may no longer exist.

POST

packages

{packageId}

documents

{documentId}

elements

A valid request URL is required to generate request examples

{
  "Type": "signingField",
  "SigningMethods": [
    "manual",
    "beid"
  ],
  "LegalNotice": {
    "Text": "read and approved"
  },
  "Location": {
    "Page": 2,
    "Top": 200,
    "Left": 200
  },
  "Dimensions": {
    "Width": 200,
    "Height": 200
  }
}

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

documentId

string<guid>

required

The target document's unique identifier A document's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

Body

application/json

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

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.

UnplacedElementId

string<guid>

required

An element's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

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

Location

object

Explicit placement. Supply together with Dimensions. Omit when using Marker or Options.

Show child attributes

Example:

{ "Page": 2, "Top": 200, "Left": 200 }

Dimensions

Element dimensions · object

Size in points. Supply together with Location. Omit when using Marker or Options.

Show child attributes

Example:

{ "Width": 200, "Height": 200 }

Marker

string

A piece of text inside the document where an element must be. It encodes the location and dimensions of the element. Omit when using Location/Dimensions or Options. Recommended to embed at document-upload time, because after document conversion the marker may no longer be present. Its format depends on the element type:

SigningField - a #-prefixed text marker #id_height_width# (for example #SIG01_50_120#), or a #-prefixed PDF field id #id that names an existing signature field.
Form fields (TextBoxField, CheckBoxField) - an @-prefixed text marker @id_height_width#, with @id_TB_height_width# for a text box and @id_CB_height_width# for a check box, or a @-prefixed PDF field id @id that names an existing form field.
RadioGroup cannot be placed with a text marker; use Options instead.

See the Field positioning guide.

Pattern: ^[#@][a-zA-Z]+(?:\d*\.)?\d+(?:_(?:TB_|CB_)?(?:\d*\.)?\d+_(?:\d*\.)?\d+#)?$

Options

object[]

Radio-group buttons, each with a Name, Location and Dimensions. Supply this only when the unplaced element is a radio group; omit when using Location/Dimensions or Marker.

Show child attributes

Response

New element was created

Signing field
Check box field
Text box field
Radio group

A field that can be signed by an actor

Type

enum<string>

required

the type of element ( the discriminator of the different types of elements, for the moment there's just one! )

Available options:

SigningField,

TextBoxField,

CheckBoxField,

RadioGroup

string<guid>

An element's unique identifier

Example:

"00000000-0000-0000-0000-000000000000"

ActorId

string<guid>

Is null when no actor has been assigned to this field yet

Example:

"00000000-0000-0000-0000-000000000000"

Status

enum<string>

The status of a document element

Available options:

Pending,

InProgress,

Rejected,

Failed,

Finished,

Refused

ExternalReference

string

Maximum string length: 256

CompletedDate

string<dateTime>

Location

object

where an element is placed

Show child attributes

Example:

{ "Page": 2, "Top": 200, "Left": 200 }

UsedSigningMethod

string

The signingmethod that was used to sign this signingfield

SigningMethods

string[]

An NSEV signing method

KeyPairMappings

object[]

Show child attributes

LegalNotice

Custom legal notice text · object

Show child attributes

Dimensions

Element dimensions · object

The size of an element in points. The minimum width and height depend on the element type - a signing field must be at least 50 × 30, other elements at least 10 × 10. See the Field positioning guide.

Show child attributes

Example:

{ "Width": 200, "Height": 200 }

Get element by idRetrieves a single element on the specified document by its element ID.

A valid request URL is required to generate request examples

{
  "Type": "signingField",
  "SigningMethods": [
    "manual",
    "beid"
  ],
  "LegalNotice": {
    "Text": "read and approved"
  },
  "Location": {
    "Page": 2,
    "Top": 200,
    "Left": 200
  },
  "Dimensions": {
    "Width": 200,
    "Height": 200
  }
}

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

Authorizations

Path Parameters

Body

Response