> ## Documentation Index > Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create unplaced element > Creates one or more unplaced elements on the specified package. The request body is an array; each entry creates one unplaced element. An unplaced element is created on the package without a position on a document. It can later be positioned with the Package Elements Editor (see Get elements action url) or by creating a placed element that references it. Four element types can be created, selected by the `Type` field on each entry: signing fields, check box fields, text box fields and radio groups. Because unplaced elements carry no position, only the type-specific content (signing methods, legal notice, form-field name/label, radio options, and so on) is supplied - never a location, dimensions, marker or field identifier. ## OpenAPI ````yaml /nsev/api-reference/openapi.yaml post /packages/{packageId}/unplacedElements openapi: 3.0.0 info: title: NSEV WebPortal API version: 4.0.0 contact: name: NSEV Support Team url: https://connectivegroup.my.site.com/s/contactsupport?language=en_US description: > **Nitro Sign Enterprise Verified (NSEV) WebPortal API Version 4** A comprehensive digital signing API that enables secure document signing workflows. This API provides endpoints for managing packages, documents, elements, stakeholders, and signing processes within the NSEV platform. ## Authentication This API supports multiple authentication methods: ### Basic Authentication Traditional HTTP Basic Authentication using username and password. ### OAuth 2.0 **Client Credentials Flow (Machine-to-Machine)** - Full API access including administrative endpoints - Ideal for server-to-server integrations **Authorization Code Flow (User-based)** - Limited API access excluding administrative endpoints - Ideal for user-facing applications - Supports delegated user access scenarios ## API Variants This specification is available in two variants: - **Full API**: Complete API with all endpoints (BasicAuth + OAuth2 M2M) - **User API**: Limited API excluding admin endpoints (OAuth2 user-based only) Administrative endpoints (`/poisonqueue`, `/absenceperiods`, `/auditproofs`) are restricted to machine-to-machine authentication only. ## Versioning This API follows semantic versioning principles. Major version changes may introduce breaking changes, while minor and patch versions maintain backwards compatibility. servers: - url: '{baseUrl}/esig/webportalapi/v4' variables: baseUrl: default: https://your-tenant.sign.gonitro.com description: >- Your tenant-specific base URL, including scheme and host (e.g. https://acme.sign.gonitro.com). Each NSEV customer has a unique URL. Replace this with yours before sending a request. The esig path segment is required - the Web Application Firewall routes requests on it. security: - basicAuth: [] - bearerAuth: [] tags: - name: Configuration description: | Endpoints for retrieving system configuration settings, contact groups, templates and signing methods. - name: Packages description: | Core endpoints for creating, managing, and tracking packages throughout their lifecycle. - name: Documents description: | Endpoints for adding, removing, and managing documents within packages. Handles document upload, processing, and metadata management. - name: Elements description: | Endpoints for managing elements (fields) within documents, including signatures and other form elements. - name: Stakeholders description: | Endpoints for managing stakeholders (recipients) associated with packages and their roles in the package workflow. - name: Actors description: | Endpoints for managing individual actors within stakeholders, including their contact information and role preferences: Approver, FormFiller, Signer or Receiver - name: Process description: | Endpoints for managing the package process workflow, including process steps, parallel actions, and workflow orchestration. - name: AuditTrails description: | Modern endpoints for retrieving comprehensive audit trails as signed PDFs, verifying the integrity of audit trail data and retrieving audit events. - name: BulkActions description: | Endpoints for performing and managing bulk actions on multiple packages. - name: Users description: | Endpoints for managing user accounts, including user invitations. - name: AbsencePeriods description: | Administrative endpoints for managing user absence periods and delegation settings during out-of-office scenarios. **Access Level**: Machine-to-machine only (administrative access required) paths: /packages/{packageId}/unplacedElements: parameters: - $ref: '#/components/parameters/packageIdPathParam' post: tags: - Elements summary: Create unplaced element description: >- Creates one or more unplaced elements on the specified package. The request body is an array; each entry creates one unplaced element. An unplaced element is created on the package without a position on a document. It can later be positioned with the Package Elements Editor (see Get elements action url) or by creating a placed element that references it. Four element types can be created, selected by the `Type` field on each entry: signing fields, check box fields, text box fields and radio groups. Because unplaced elements carry no position, only the type-specific content (signing methods, legal notice, form-field name/label, radio options, and so on) is supplied - never a location, dimensions, marker or field identifier. operationId: createUnplacedElement requestBody: description: Collection of unplaced elements to be added to the package. required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/UnplacedElement' examples: unplaced-mixed: summary: Create unplaced signing field and text box value: - Type: SigningField ExternalReference: Field1 SigningMethods: - manual LegalNotice: Text: Read and approved - Type: TextBoxField Name: TextBox1 Label: textBoxLabel ToolTipLabel: textBoxTooltip IsRequired: true ExternalReference: Field3 DefaultValue: something IsMultiline: true CharLimit: 200 responses: '200': description: Ok content: application/json: schema: type: array items: $ref: '#/components/schemas/UnplacedElementResult' '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/UnAuthorized' '404': $ref: '#/components/responses/NotFound.Package' '409': description: Unplaced elements could not be created for the package content: application/json: schema: type: array items: $ref: '#/components/schemas/Error' components: parameters: packageIdPathParam: name: packageId in: path required: true description: The target package's unique identifier schema: $ref: '#/components/schemas/Package.Id' schemas: UnplacedElement: oneOf: - $ref: '#/components/schemas/UnplacedSigningField' - $ref: '#/components/schemas/UnplacedCheckBox' - $ref: '#/components/schemas/UnplacedTextBox' - $ref: '#/components/schemas/UnplacedRadioGroup' - $ref: '#/components/schemas/UnplacedComboBox' discriminator: propertyName: Type mapping: SigningField: $ref: '#/components/schemas/UnplacedSigningField' CheckBoxField: $ref: '#/components/schemas/UnplacedCheckBox' TextBoxField: $ref: '#/components/schemas/UnplacedTextBox' RadioGroup: $ref: '#/components/schemas/UnplacedRadioGroup' ComboBoxField: $ref: '#/components/schemas/UnplacedComboBox' UnplacedElementResult: oneOf: - $ref: '#/components/schemas/UnplacedSigningFieldResult' - $ref: '#/components/schemas/UnplacedCheckBoxFieldResult' - $ref: '#/components/schemas/UnplacedTextBoxFieldResult' - $ref: '#/components/schemas/UnplacedRadioGroupResult' - $ref: '#/components/schemas/UnplacedComboBoxFieldResult' discriminator: propertyName: Type mapping: SigningField: $ref: '#/components/schemas/UnplacedSigningFieldResult' CheckBoxField: $ref: '#/components/schemas/UnplacedCheckBoxFieldResult' TextBoxField: $ref: '#/components/schemas/UnplacedTextBoxFieldResult' RadioGroup: $ref: '#/components/schemas/UnplacedRadioGroupResult' ComboBoxField: $ref: '#/components/schemas/UnplacedComboBoxFieldResult' Error: title: Error type: object description: Something that went wrong example: ErrorCode: Something.WentWrong ErrorMessage: Something went wrong properties: ErrorCode: type: string description: >- An error code of something that went wrong, in the form of 'Subject.Error:value' ErrorMessage: type: string description: A human-readable explanation of what went wrong Package.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A package's unique identifier UnplacedSigningField: title: Unplaced signing field allOf: - $ref: '#/components/schemas/UnplacedElementBase' - type: object description: A field that can be signed by an actor properties: Type: enum: - SigningField SigningMethods: type: array items: $ref: '#/components/schemas/SigningMethodWithKeyPair' description: >- The signing methods that may be used to sign this signing field. Always supply an array, even for a single method. Each entry is an object with a `Name` and an optional `KeyPair`; a bare signing-method name string is also accepted as shorthand for `{ "Name": "" }`. When omitted, the package's `DefaultSigningMethods` (NSEV v8.5+) are applied to the field. LegalNotice: allOf: - $ref: '#/components/schemas/CreateLegalNotice' description: >- An optional legal notice added to the signing field. Supply either a custom `Text` or the `Name` of a notice configured in the Config Index. example: Type: SigningField ExternalReference: Field1 SigningMethods: - manual LegalNotice: Text: Read and approved UnplacedCheckBox: title: Unplaced check box allOf: - $ref: '#/components/schemas/UnplacedElementBase' - $ref: '#/components/schemas/UnplacedFormFieldBase' - type: object description: Parameters for creating an unplaced check box element properties: Type: enum: - CheckBoxField CheckedByDefault: type: boolean description: Checked by default indicator example: Type: checkBoxField ExternalReference: Field check box Name: CheckBox1 Label: CheckBoxLabel ToolTipLabel: check box tooptip IsRequired: false CheckedByDefault: false UnplacedTextBox: title: Unplaced text box allOf: - $ref: '#/components/schemas/UnplacedElementBase' - $ref: '#/components/schemas/UnplacedFormFieldBase' - type: object description: Parameters for creating an unplaced text box element properties: Type: enum: - TextBoxField DefaultValue: type: string description: Default text box value maxLength: 2048 IsMultiline: type: boolean description: Multiline indicator CharLimit: type: integer nullable: true description: Limits the number of characters on the text box field minimum: 1 maximum: 2048 InputType: $ref: '#/components/schemas/InputType' example: Type: textBoxField Name: TextBox1 Label: textBoxLabel ToolTipLabel: textBoxTooltip IsRequired: true ExternalReference: Field3 DefaultValue: something IsMultiline: true CharLimit: 200 UnplacedRadioGroup: title: Unplaced radio group allOf: - $ref: '#/components/schemas/UnplacedElementBase' - $ref: '#/components/schemas/UnplacedFormFieldBase' - type: object description: Parameters for creating an unplaced radio button group required: - Options properties: Type: enum: - RadioGroup Options: type: array description: >- The radio buttons in the group. Supply at least two. For an unplaced radio group each option carries only its name and label - positions are assigned later when the group is placed. items: $ref: '#/components/schemas/UnplacedRadioOption' minItems: 2 example: Type: radioGroup Name: radioGroup1 Label: radioGroup1Label ExternalReference: Field4 Options: - IsSelected: true Name: buton1 Label: label1 - IsSelected: false Name: buton2 Label: label2 UnplacedComboBox: title: Unplaced combo box allOf: - $ref: '#/components/schemas/UnplacedElementBase' - $ref: '#/components/schemas/UnplacedFormFieldBase' - type: object description: | Available as of NSEV v8.5. Parameters for creating an unplaced combo box (dropdown) element. properties: Type: enum: - ComboBoxField Options: type: array description: >- The combo box options. When supplied, provide at least one, and option values (the `ExportValue`, or the `DisplayLabel` when no `ExportValue` is set) must be unique within the field. items: $ref: '#/components/schemas/ComboBoxOption' minItems: 1 maxItems: 100 AllowCustomInput: type: boolean default: false description: >- Whether the end user can type a custom value instead of selecting one of the options. Defaults to false. DefaultValue: type: string maxLength: 2048 description: >- The value selected by default, which the end user can change. When `Options` are supplied, must match the `ExportValue` (or the `DisplayLabel` when no `ExportValue` is set) of one of the `Options`, even when `AllowCustomInput` is true. Because option values are capped at 256 characters, the effective maximum length is 256, despite the 2048-character validation ceiling. example: Type: ComboBoxField Name: Dropdown1 Label: Select a country ExternalReference: Field5 Options: - DisplayLabel: United States ExportValue: US - DisplayLabel: United Kingdom ExportValue: UK AllowCustomInput: false DefaultValue: US UnplacedSigningFieldResult: title: Unplaced signing field (result) allOf: - $ref: '#/components/schemas/UnplacedElementBaseResult' - type: object description: A field that can be signed by an actor properties: Type: enum: - SigningField SigningMethods: type: array items: $ref: '#/components/schemas/SigningMethod' LegalNotice: $ref: '#/components/schemas/LegalNotice' 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' UnplacedCheckBoxFieldResult: title: Unplaced check box field (result) allOf: - $ref: '#/components/schemas/UnplacedElementBaseResult' - $ref: '#/components/schemas/UnplacedFormFieldBaseResult' - type: object description: Parameters for creating a check box field properties: Type: enum: - CheckBoxField DefaultValue: type: boolean description: Is the check box field checked by default Checked: type: boolean description: The value of the completed check box field example: Id: 5F2D5145-D31C-4D9E-8635-F687D7CC414A ActorId: A6BB68DD-F295-45B7-85D3-1D2DFE55A721 Type: checkBoxField Status: Pending Name: checkBox1 Label: some label ToolTipLabel: some tooltip IsRequired: false DefaultValue: true Checked: true UnplacedTextBoxFieldResult: title: Unplaced text box field (result) allOf: - $ref: '#/components/schemas/UnplacedElementBaseResult' - $ref: '#/components/schemas/UnplacedFormFieldBaseResult' - type: object description: Parameters for creating a text box field properties: Type: enum: - TextBoxField DefaultValue: type: string description: The template for default value of the text box IsMultiline: type: boolean description: Defines if the text box field should be multiline CharLimit: type: integer nullable: true description: Limits the number of characters on the text box field InputType: $ref: '#/components/schemas/InputType' Value: type: string description: The value of the completed text box field example: Id: 5F2D5145-D31C-4D9E-8635-F687D7CC414A ActorId: A6BB68DD-F295-45B7-85D3-1D2DFE55A721 Type: textBoxField Status: Pending ExternalReference: external reference Name: checkBox1 Label: some label ToolTipLabel: some tooltip IsRequired: false DefaultValue: something IsMultiline: true CharLimit: 200 Value: text UnplacedRadioGroupResult: title: Unplaced radio group (result) allOf: - $ref: '#/components/schemas/UnplacedElementBaseResult' - $ref: '#/components/schemas/UnplacedFormFieldBaseResult' - type: object description: Parameters for creating a radio button group properties: Type: enum: - RadioGroup Selected: type: string description: The name of selected option Options: type: array description: The radio button group Options items: $ref: '#/components/schemas/UnplacedRadioOptionResult' example: Id: 5F2D5145-D31C-4D9E-8635-F687D7CC414A ActorId: A6BB68DD-F295-45B7-85D3-1D2DFE55A721 Type: textBoxField Status: Pending ExternalReference: external reference Name: checkBox1 Label: some label ToolTipLabel: some tooltip IsRequired: false Options: - Name: option1 Label: option1 label IsSelected: true - Name: option2 Label: option2 label IsSelected: false UnplacedComboBoxFieldResult: title: Unplaced combo box field (result) allOf: - $ref: '#/components/schemas/UnplacedElementBaseResult' - $ref: '#/components/schemas/UnplacedFormFieldBaseResult' - type: object description: | Available as of NSEV v8.5. A combo box (dropdown) field. properties: Type: enum: - ComboBoxField Options: type: array description: The combo box options items: $ref: '#/components/schemas/ComboBoxOptionResult' AllowCustomInput: type: boolean description: >- Whether the end user can type a custom value instead of selecting one of the options IsOverridable: type: boolean description: >- Whether the options can be modified. False when they are sourced from an existing PDF form field - via `FieldId` or a `@id` PDF-field marker; true for fields created with request-supplied options. Value: type: string description: The value of the completed combo box field DefaultValue: type: string description: The export value selected by default example: Id: 5F2D5145-D31C-4D9E-8635-F687D7CC414A ActorId: A6BB68DD-F295-45B7-85D3-1D2DFE55A721 Type: ComboBoxField Status: Pending Name: Dropdown1 Label: Select a country IsRequired: false Options: - DisplayLabel: United States ExportValue: US - DisplayLabel: United Kingdom ExportValue: UK AllowCustomInput: false IsOverridable: true DefaultValue: US ValidationError: title: Validation error allOf: - $ref: '#/components/schemas/Error' - description: Request failed validation example: ErrorCode: Name.MinimumLength:6 ErrorMessage: The minimum length for a name is 6 PackageNotFoundError: title: Package not found allOf: - $ref: '#/components/schemas/NotFoundError' example: ErrorCode: Package.NotFound:00000000-0000-0000-0000-000000000000 ErrorMessage: >- The package with id '00000000-0000-0000-0000-000000000000' could not be found Guid: title: GUID type: string description: A globally unique identifier format: guid example: 00000000-0000-0000-0000-000000000000 UnplacedElementBase: type: object description: An unplaced element on a package, e.g. a signing field required: - Type properties: Type: $ref: '#/components/schemas/Element.Type' ExternalReference: $ref: '#/components/schemas/ExternalReference' SigningMethodWithKeyPair: title: Signing method with key pair type: object description: >- A signing method, optionally pinned to a key pair. In requests, a bare signing-method name string is also accepted anywhere this object is expected, as shorthand for `{ "Name": "" }`. Responses always return the object form. required: - Name properties: Name: description: The name of an NSEV signing method type: string example: MailOtp:MailOtp KeyPair: description: >- the name of the keypair to be used for signing, the default keypair will be used when null type: string example: MyKeyPair CreateLegalNotice: oneOf: - $ref: '#/components/schemas/LegalNotice' - type: object title: Named legal notice from Config Index properties: Name: description: >- The name of a legal notice configured in the Config Index (for example `LegalNotice1`), whose text is also set there. The language the notice is displayed in depends on the language of the document. Use either `Name` or `Text`, not both. type: string maxLength: 20 example: LegalNotice1 UnplacedFormFieldBase: type: object description: A unplaced form field required: - Name properties: Name: type: string description: The name of the form field maxLength: 256 Label: type: string description: The label or alternative name of the form field maxLength: 256 ToolTipLabel: type: string description: The tool tip label of the form field maxLength: 256 IsRequired: type: boolean InputType: title: Text box input type type: string description: > Available as of NSEV v8.5. A hint for how the text box is rendered. Defaults to `Text` when omitted. The hint does not constrain `DefaultValue`, `IsMultiline` or `CharLimit` - the API applies no format validation based on it. enum: - Text - Date - Time - DateTime - Number UnplacedRadioOption: type: object description: Parameters for creating a radio button option required: - Name properties: Name: type: string description: The name/choice of the option maxLength: 256 Label: type: string description: The label or alternative name of the option maxLength: 256 IsSelected: type: boolean description: Is the option pre-selected ComboBoxOption: title: Combo box option type: object description: > Available as of NSEV v8.5. A combo box option: the label shown to the end user and the value stored when it is selected. required: - DisplayLabel properties: DisplayLabel: type: string description: The display label shown to the end user maxLength: 256 ExportValue: type: string description: >- The value stored when this option is selected. When omitted, the `DisplayLabel` is used as the value. maxLength: 256 UnplacedElementBaseResult: type: object description: An element on a document, e.g. a signing field required: - Type properties: Id: $ref: '#/components/schemas/Element.Id' ActorId: allOf: - $ref: '#/components/schemas/Actor.Id' - nullable: true type: string Type: $ref: '#/components/schemas/Element.Type' Status: $ref: '#/components/schemas/Element.Status' ExternalReference: $ref: '#/components/schemas/ExternalReference' MarkerType: $ref: '#/components/schemas/Element.MarkerType' MarkerId: $ref: '#/components/schemas/Element.MarkerId' SigningMethod: title: Signing method name type: string description: An NSEV signing method example: manual LegalNotice: title: Custom legal notice text type: object properties: Text: description: >- A custom legal notice the signer must retype before placing their signature. Use this when the notice is not one of the named notices configured in the Config Index. Write it in the same language as the package's documents. Legal notices are case-sensitive. type: string maxLength: 1000 example: Read and approved UnplacedFormFieldBaseResult: type: object description: A form field that can be completed by an actor properties: Name: type: string description: The name of the form field Label: type: string description: The label or alternative name of the form field ToolTipLabel: type: string description: The tool tip label of the form field IsRequired: type: boolean description: Is the form field required UnplacedRadioOptionResult: allOf: - type: object description: Parameters for creating a radio button option properties: Name: type: string description: The name/choice of the option Label: type: string description: The label or alternative name of the option IsSelected: type: boolean description: Is the option pre-selected ComboBoxOptionResult: title: Combo box option (result) type: object description: | Available as of NSEV v8.5. A combo box option in a response. properties: DisplayLabel: type: string description: The display label shown to the end user ExportValue: type: string description: The value stored when this option is selected NotFoundError: title: Not found allOf: - $ref: '#/components/schemas/Error' - description: The resource could not be found example: ErrorCode: Document.NotFound:00000000-0000-0000-0000-000000000000 ErrorMessage: >- The document with id '00000000-0000-0000-0000-000000000000' could not be found Element.Type: type: string description: | The type of element - the discriminator across the element variants. The `ComboBoxField` value is available as of NSEV v8.5. nullable: false enum: - SigningField - TextBoxField - CheckBoxField - RadioGroup - ComboBoxField ExternalReference: type: string maxLength: 256 description: >- 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. Element.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: An element's unique identifier Actor.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: This actor's unique identifier Element.Status: type: string description: The status of a document element enum: - Pending - InProgress - Rejected - Failed - Finished - Refused Element.MarkerType: type: string description: the type of marker (if set) nullable: true enum: - None - Text - PdfFormField Element.MarkerId: type: string description: A piece of text or PDF field identifier nullable: true responses: ValidationFailed: description: Request failed validation content: application/json: schema: type: array items: $ref: '#/components/schemas/ValidationError' UnAuthorized: description: Caller is unauthorized to perform this operation NotFound.Package: description: Package could not be found content: application/json: schema: type: array items: $ref: '#/components/schemas/PackageNotFoundError' securitySchemes: basicAuth: type: http scheme: basic bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Bearer token authentication using JSON Web Tokens (JWT) or opaque tokens. **Usage**: Send the access token in the Authorization header: ``` Authorization: Bearer ``` ````