> ## 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. # 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. ## OpenAPI ````yaml /nsev/api-reference/openapi.yaml post /packages/{packageId}/documents 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}/documents: parameters: - $ref: '#/components/parameters/packageIdPathParam' post: tags: - Documents summary: Add document description: >- 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. operationId: createDocument parameters: - in: query name: async schema: type: boolean default: false description: >- 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. requestBody: $ref: '#/components/requestBodies/CreateDocument' responses: '201': $ref: '#/components/responses/DocumentCreated' '202': description: Accepted, the document will be processed asynchronously headers: Location: description: The package information location schema: type: string format: url '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/UnAuthorized' '404': $ref: '#/components/responses/NotFound.Package' '409': description: Document could not be added to 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' requestBodies: CreateDocument: description: Parameters for creating a document required: true content: application/json: schema: $ref: '#/components/schemas/CreateDocumentWithBase64Document' examples: existing: summary: PDF document (existing spec example) value: Name: string Language: en ExternalReference: string Elements: - Type: signingField ExternalReference: myManualField SigningMethods: - manual Location: Page: 1 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 - Type: signingField ExternalReference: myBeidField FieldId: signme SigningMethods: - beid Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 ProofCorrelationId: string DocumentOptions: targetType: application/pdf pdfOptions: targetFormat: pdfa1a base64data: string contentType: application/pdf pdf-base64: summary: PDF document with two signing fields (Base64, application/json) value: Name: string Language: en ExternalReference: string Elements: - Type: signingField ExternalReference: myManualField SigningMethods: - manual Location: Page: 1 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 - Type: signingField ExternalReference: myBeidField FieldId: signme SigningMethods: - beid Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 ProofCorrelationId: string DocumentOptions: targetType: application/pdf pdfOptions: targetFormat: pdfa1a base64data: string contentType: application/pdf async-keep-signatures: summary: Asynchronous upload preserving existing signatures and fields value: name: string language: en externalReference: string documentOptions: targetType: application/pdf contentType: application/pdf pdfOptions: targetFormat: pdf pdfErrorHandling: detectfixwarn KeepSignatures: false KeepSigningFields: false KeepFormFields: false base64data: string multipart/form-data: schema: type: object required: - Document - Parameters properties: Parameters: allOf: - $ref: '#/components/schemas/CreateDocument' - type: object properties: DocumentOptions: $ref: '#/components/schemas/CreateDocument.DocumentOptions' Document: description: Multipart attached document type: string format: binary Representation: description: Multipart attached representation type: string format: binary encoding: document: contentType: >- application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/plain, application/xml representation: contentType: application/pdf responses: DocumentCreated: description: Document was created headers: Location: description: Location of the newly created document schema: type: string format: url content: application/json: schema: $ref: '#/components/schemas/DocumentCreatedSync' 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' schemas: 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 CreateDocumentWithBase64Document: allOf: - $ref: '#/components/schemas/CreateDocument' - type: object required: - DocumentOptions properties: DocumentOptions: allOf: - $ref: '#/components/schemas/CreateDocument.DocumentOptions' - $ref: '#/components/schemas/CreateDocument.Base64Document' - required: - ContentType properties: ContentType: allOf: - $ref: '#/components/schemas/MediaType' - enum: - application/pdf - application/xml - application/msword - >- application/vnd.openxmlformats-officedocument.wordprocessingml.document - text/plain RepresentationOptions: allOf: - $ref: '#/components/schemas/CreateDocument.Base64Document' - required: - ContentType properties: ContentType: allOf: - $ref: '#/components/schemas/MediaType' - enum: - application/pdf CreateDocument: type: object description: Parameters for creating a document additionalProperties: false required: - Name - Language properties: Name: type: string description: >- 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. minLength: 1 maxLength: 150 Language: allOf: - $ref: '#/components/schemas/Language' - description: >- 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. IsOptional: type: boolean default: false description: >- 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: $ref: '#/components/schemas/ExternalReference' Elements: type: array description: >- A list of elements (that aren't linked to an actor at once) on the created document items: $ref: '#/components/schemas/CreateElement' ProofCorrelationId: type: string deprecated: true description: >- Id for correlating this document with other resources in the proofs system CreateDocument.DocumentOptions: type: object allOf: - properties: TargetType: type: string description: >- The media type the document will be converted to. Only takes effect when the server is configured for document conversion. enum: - application/pdf - application/xml PdfOptions: type: object description: >- Optional PDF conversion and validation parameters. Only applies when the target type is application/pdf. properties: TargetFormat: type: string description: >- The targetFormat defines if an extra conversion needs to be done enum: - pdf - pdfa1a - pdfa2a example: pdfa1a PdfErrorHandling: type: string description: How to deal with PDFs containing minor flaws enum: - Ignore - DetectWarn - DetectFail - DetectFixWarn - DetectFixFail - $ref: '#/components/schemas/DocumentActions' DocumentCreatedSync: type: object description: A single document additionalProperties: false properties: Id: $ref: '#/components/schemas/Document.Id' PackageId: $ref: '#/components/schemas/Package.Id' Name: $ref: '#/components/schemas/Document.Name' CreationDate: $ref: '#/components/schemas/CreationDate' MediaType: allOf: - $ref: '#/components/schemas/MediaType' - enum: - application/pdf - application/xml Language: $ref: '#/components/schemas/Language' Status: $ref: '#/components/schemas/Document.Status' Elements: type: array description: The document's elements items: $ref: '#/components/schemas/Element' ExternalReference: $ref: '#/components/schemas/ExternalReference' ProofCorrelationId: $ref: '#/components/schemas/ProofCorrelationId' OrderIndex: $ref: '#/components/schemas/Document.OrderIndex' 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 CreateDocument.Base64Document: type: object description: Contains a document's base64 data and media type additionalProperties: false required: - Base64data properties: Base64data: type: string description: Attached document format: base64 nullable: false minLength: 1 maxLength: 200000000 MediaType: nullable: false type: string format: mediaType description: The media type of a file example: application/pdf Language: type: string format: languageCode description: A country's 2 letter ISO code (ISO 639-1) example: en 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. CreateElement: oneOf: - $ref: '#/components/schemas/CreateElementFromUnplacedElement' - $ref: '#/components/schemas/CreateSigningField' - $ref: '#/components/schemas/CreateCheckBoxField' - $ref: '#/components/schemas/CreateTextBoxField' - $ref: '#/components/schemas/CreateRadioGroup' discriminator: propertyName: Type mapping: SigningField: $ref: '#/components/schemas/CreateSigningField' CheckBoxField: $ref: '#/components/schemas/CreateCheckBoxField' TextBoxField: $ref: '#/components/schemas/CreateTextBoxField' RadioGroup: $ref: '#/components/schemas/CreateRadioGroup' example: Type: signingField Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 DocumentActions: type: object description: >- Document actions to be performed on Draft document with IsActionNeeded flag set to true. properties: KeepSignatures: type: boolean description: >- When true, existing signatures detected in the document are applied to the document file. Default is false. Cannot be true at the same time as KeepFormFields. default: false KeepSigningFields: type: boolean description: >- When true, detected signing field markers are converted to actual signing fields. Default is false. default: false KeepFormFields: type: boolean description: >- When true, detected form field markers are converted to actual form fields. Default is false. Cannot be true at the same time as KeepSignatures. default: false Document.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A document's unique identifier Document.Name: type: string nullable: false description: Name of the document minLength: 1 maxLength: 150 example: example document CreationDate: type: string format: date-time description: When the resource was created Document.Status: type: string description: The status of a document enum: - Draft - Pending - InProgress - Ending - Finished - Rejected - Revoked - Expired - Failed - Processing - ProcessingFailed Element: oneOf: - $ref: '#/components/schemas/SigningField' - $ref: '#/components/schemas/CheckBoxField' - $ref: '#/components/schemas/TextBoxField' - $ref: '#/components/schemas/RadioGroup' discriminator: propertyName: Type mapping: SigningField: $ref: '#/components/schemas/SigningField' CheckBoxField: $ref: '#/components/schemas/CheckBoxField' TextBoxField: $ref: '#/components/schemas/TextBoxField' RadioGroup: $ref: '#/components/schemas/RadioGroup' ProofCorrelationId: type: string deprecated: true description: Id for correlating with other resources in the proofs system Document.OrderIndex: type: integer description: The Order Index of the document. 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 CreateElementFromUnplacedElement: title: Place an unplaced element type: object description: > 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](/nsev/build/guides/field-positioning). additionalProperties: false required: - UnplacedElementId properties: UnplacedElementId: $ref: '#/components/schemas/Element.Id' ExternalReference: $ref: '#/components/schemas/ExternalReference' Location: allOf: - $ref: '#/components/schemas/Element.Location' - description: >- Explicit placement. Supply together with `Dimensions`. Omit when using `Marker` or `Options`. Dimensions: allOf: - $ref: '#/components/schemas/Element.Dimensions' - description: >- Size in points. Supply together with `Location`. Omit when using `Marker` or `Options`. Marker: description: >- 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](/nsev/build/guides/field-positioning). type: string pattern: >- ^[#@][a-zA-Z]+(?:\d*\.)?\d+(?:_(?:TB_|CB_)?(?:\d*\.)?\d+_(?:\d*\.)?\d+#)?$ Options: description: >- 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`. type: array items: type: object properties: Name: type: string description: The name of the unplaced option Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' CreateSigningField: title: Signing field allOf: - $ref: '#/components/schemas/CreateElementBase' - type: object description: Parameters for creating a signing field 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": "" }`. LegalNotice: allOf: - $ref: '#/components/schemas/CreateLegalNotice' description: >- An optional legal notice added to the signing field: text the signer must retype before signing. Supply either a custom `Text` or the `Name` of a notice configured in the Config Index. When using a long legal notice, size the signing field accordingly - a small field with a long notice can shrink the font until the text is unreadable. CreateCheckBoxField: title: Check box field allOf: - $ref: '#/components/schemas/CreateFormFieldBase' - type: object description: Parameters for creating a check box field properties: Type: enum: - CheckBoxField DefaultValue: type: boolean default: false description: >- Whether the checkbox is checked by default. The end user can still change it. When the document already contains a prefilled form field, leave this false to avoid overwriting the existing value. Defaults to false. CreateTextBoxField: title: Text box field allOf: - $ref: '#/components/schemas/CreateFormFieldBase' - type: object description: Parameters for creating a text box field properties: Type: enum: - TextBoxField DefaultValue: type: string description: >- A value prefilled into the text box, which the end user can change. When the document already contains a prefilled form field, leave this null to avoid overwriting the existing value. IsMultiline: type: boolean default: false description: >- Whether the text box accepts multiple lines. When true, the text box is scrollable. Defaults to false. CharLimit: type: integer nullable: true description: >- The maximum number of characters that may be entered in the text box. CreateRadioGroup: title: Radio group type: object description: > Parameters for creating a radio button group. Place the group in **one** of two ways: - **By coordinates** - supply `Options`, each button positioned by its own `Location` and `Dimensions`. - **On an existing PDF field** - supply `FieldId`. Do not combine the two. A radio group cannot be placed with a text marker. For the full rules see the [Field positioning guide](/nsev/build/guides/field-positioning). additionalProperties: false properties: Type: type: string description: the type of element enum: - RadioGroup ExternalReference: $ref: '#/components/schemas/ExternalReference' Name: type: string description: >- The name of the radio group. Must be unique per document. Do not use `Name` when referencing an existing radio group with `FieldId`. 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 default: false description: >- Whether the radio group is mandatory. When true, the end user must select an option. When the document already contains a prefilled form field, leave this null to avoid overwriting the original value. Defaults to false. Options: type: array description: >- The radio buttons in the group, each positioned by its own `Location` and `Dimensions`. Supply these to place the group by coordinates; omit when using `FieldId`. items: $ref: '#/components/schemas/CreateRadioOption' FieldId: type: string description: >- The name of an existing input field on the document. Supply this to place the group on an existing PDF field; omit when supplying `Options`. Recommended to do this at document upload time, because after a document conversion the field with this identifier may no longer exist. SigningField: title: Signing field allOf: - $ref: '#/components/schemas/ElementBase' - type: object description: A field that can be signed by an actor properties: Location: $ref: '#/components/schemas/Element.Location' UsedSigningMethod: type: string description: The signingmethod that was used to sign this signingfield SigningMethods: type: array items: $ref: '#/components/schemas/SigningMethod' KeyPairMappings: type: array items: $ref: '#/components/schemas/KeyPairMapping' LegalNotice: $ref: '#/components/schemas/LegalNotice' Dimensions: $ref: '#/components/schemas/Element.Dimensions' CheckBoxField: title: Check box field allOf: - $ref: '#/components/schemas/ElementBase' - $ref: '#/components/schemas/FormFieldBase' - type: object description: Parameters for creating a check box field properties: Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' DefaultValue: type: boolean description: Is the check box field checked by default Checked: type: boolean description: The value of the completed check box field TextBoxField: title: Text box field allOf: - $ref: '#/components/schemas/ElementBase' - $ref: '#/components/schemas/FormFieldBase' - type: object description: Parameters for creating a text box field properties: Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' 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 Value: type: string description: The value of the completed text box field RadioGroup: title: Radio group allOf: - $ref: '#/components/schemas/ElementBase' - $ref: '#/components/schemas/FormFieldBase' - type: object description: Parameters for creating a radio button group properties: Selected: type: string description: The name of selected option Options: type: array description: The radio button group Options items: $ref: '#/components/schemas/RadioOption' Element.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: An element's unique identifier Element.Location: type: object description: where an element is placed required: - Page - Left - Top properties: Page: type: integer description: >- The page of the document the element is placed on. Pages are 1-based: 1 is the first page; 0 must not be used. To count from the end, use negative integers: -1 is the last page, -2 the second-to-last, and so on. Top: type: number format: float minimum: 0 description: how far from the top edge of the document this is placed Left: type: number format: float minimum: 0 description: how far from the left edge of the document this is placed example: Page: 2 Top: 200 Left: 200 Element.Dimensions: title: Element dimensions type: object description: > 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](/nsev/build/guides/field-positioning). required: - Width - Height properties: Width: type: number format: float description: width of the element maximum: 999999 Height: type: number format: float description: height of the element maximum: 999999 example: Width: 200 Height: 200 CreateElementBase: type: object description: > Parameters common to every created element, including where it is placed. 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). - **Existing PDF form field** - supply `FieldId`. Do not combine methods. Radio groups are placed per-option (see `CreateRadioGroup`), and a server-signed signing field may be created invisible with none of these. For the full rules, marker formats and per-type minimum dimensions, see the [Field positioning guide](/nsev/build/guides/field-positioning). additionalProperties: false required: - Type properties: Type: type: string description: the type of element enum: - SigningField - CheckBoxField - TextBoxField - RadioGroup ExternalReference: $ref: '#/components/schemas/ExternalReference' Location: allOf: - $ref: '#/components/schemas/Element.Location' - description: >- Explicit placement. Supply together with `Dimensions`. Omit when using `Marker` or `FieldId`. Dimensions: allOf: - $ref: '#/components/schemas/Element.Dimensions' - description: >- Size in points. Supply together with `Location`. Omit when using `Marker` or `FieldId`. Marker: type: string pattern: >- ^[#@][a-zA-Z]+(?:\d*\.)?\d+(?:_(?:TB_|CB_)?(?:\d*\.)?\d+_(?:\d*\.)?\d+#)?$ description: >- A piece of text inside the document marking where the element must be placed; it encodes the element's location and dimensions. Omit when using `Location`/`Dimensions` or `FieldId`. Recommended to embed at document-upload time, because after document conversion the marker may no longer be present. The 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](/nsev/build/guides/field-positioning). FieldId: type: string description: >- The name of an existing form field in the uploaded document to attach this element to; must be unique within the document. Omit when using `Location`/`Dimensions` or `Marker`. Recommended to do this at document-upload time, because after document conversion the field may no longer exist. SigningMethodWithKeyPair: title: Signing method with key pair type: object 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 CreateFormFieldBase: allOf: - $ref: '#/components/schemas/CreateElementBase' - type: object description: Parameters for creating a form field element additionalProperties: false properties: Name: type: string description: >- The name of the form field. Must be unique per document. Only use `Name` when placing the field by explicit location and dimensions or by marker; do not use it when referencing an existing form field with `FieldId`. Label: type: string description: The label or alternative name of the form field. ToolTipLabel: type: string description: >- The text shown as a tooltip when the user hovers over the form field. When the document already contains a prefilled form field with a tooltip, leave this null to avoid overwriting the original value. IsRequired: type: boolean default: false description: >- Whether the form field is mandatory. When true, the end user must complete it. When the document already contains a prefilled form field, leave this null to avoid overwriting the original value. Defaults to false. CreateRadioOption: allOf: - type: object description: Parameters for creating a radio button option properties: Name: type: string description: The name (choice value) of the radio button. Label: type: string description: The label or alternative name of the radio button. IsSelected: type: boolean description: Whether this radio button is selected by default. Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' ElementBase: 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 description: Is null when no actor has been assigned to this field yet type: string Type: $ref: '#/components/schemas/Element.Type' Status: $ref: '#/components/schemas/Element.Status' ExternalReference: $ref: '#/components/schemas/ExternalReference' CompletedDate: type: string format: dateTime SigningMethod: title: Signing method name type: string description: An NSEV signing method example: manual KeyPairMapping: type: object description: >- A mapping between signing method and the keypair to be used for signing with this method. If a signing method is not mentioned in this list, then the default keypair will be used when signing properties: SigningMethodName: description: The name of an NSEV signing method type: string example: MailOtp:MailOtp KeyPair: description: >- The name of the keypair that is used for signing if the corresponding signing method is chosen type: string example: MyKeyPair 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 FormFieldBase: 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 RadioOption: 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 Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' Actor.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: This actor's unique identifier Element.Type: type: string description: >- the type of element ( the discriminator of the different types of elements, for the moment there's just one! ) nullable: false enum: - SigningField - TextBoxField - CheckBoxField - RadioGroup Element.Status: type: string description: The status of a document element enum: - Pending - InProgress - Rejected - Failed - Finished - Refused 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 ``` ````