> ## 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. # Update process > Overwrites the package's entire process with the supplied steps. The body is a 2D array: the outer array is the ordered list of steps, and each inner array is the set of actors that run in parallel within that step. The same step-ordering and actor-type rules as Create process step apply. ## OpenAPI ````yaml /nsev/api-reference/openapi.yaml put /packages/{packageId}/process 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}/process: summary: | All actions that need to be performed as a set of steps. Every array is a set of actions that can be completed in parallel. parameters: - $ref: '#/components/parameters/packageIdPathParam' put: tags: - Process summary: Update process description: >- Overwrites the package's entire process with the supplied steps. The body is a 2D array: the outer array is the ordered list of steps, and each inner array is the set of actors that run in parallel within that step. The same step-ordering and actor-type rules as Create process step apply. operationId: updateProcess requestBody: content: application/json: schema: type: array items: type: array items: $ref: '#/components/schemas/CreateActorWithStakeholderId' examples: two-steps: summary: Process steps were updated value: - - Type: approver StakeholderId: 00000000-0000-0000-0000-000000000001 SuppressNotifications: false RedirectUrl: https://myserver.example.org/return - - Type: signer StakeholderId: 00000000-0000-0000-0000-000000000002 SuppressNotifications: false Elements: - Type: signingField DocumentId: 00000000-0000-0000-0000-000000000003 SigningMethods: - manual Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 RedirectUrl: https://myserver.example.org/return responses: '200': description: Process steps were updated '401': $ref: '#/components/responses/UnAuthorized' '404': $ref: '#/components/responses/NotFound.Package' components: parameters: packageIdPathParam: name: packageId in: path required: true description: The target package's unique identifier schema: $ref: '#/components/schemas/Package.Id' schemas: CreateActorWithStakeholderId: allOf: - $ref: '#/components/schemas/CreateActor' - type: object required: - StakeholderId properties: StakeholderId: $ref: '#/components/schemas/Stakeholder.Id' Package.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A package's unique identifier CreateActor: oneOf: - $ref: '#/components/schemas/CreateSignerActor' - $ref: '#/components/schemas/CreateApproverActor' - $ref: '#/components/schemas/CreateFormFillerActor' - $ref: '#/components/schemas/CreateReceiverActor' discriminator: propertyName: Type mapping: Signer: $ref: '#/components/schemas/CreateSignerActor' Approver: $ref: '#/components/schemas/CreateApproverActor' FormFiller: $ref: '#/components/schemas/CreateFormFillerActor' Receiver: $ref: '#/components/schemas/CreateReceiverActor' example: Type: signer SuppressNotifications: false Elements: - Id: 5a5365e1-3780-47c7-9657-a1496be6ea5e - Type: signingField DocumentId: c05866bc-6b5a-4b5b-a4c1-b76895469f6f Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 Stakeholder.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A stakeholder's unique identifier 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 CreateSignerActor: title: Signer allOf: - $ref: '#/components/schemas/CreateActorBase' - type: object description: Signs one or more signing fields properties: Type: enum: - Signer Elements: type: array description: The actor's elements items: oneOf: - allOf: - $ref: '#/components/schemas/CreateSigningField' - title: New signing field on a document properties: DocumentId: $ref: '#/components/schemas/Document.Id' - title: Existing element by Id properties: Id: $ref: '#/components/schemas/Element.Id' RedirectUrl: type: string format: url description: > Url to which the stakeholder is redirected after completing this action RedirectType: type: string enum: - AfterSession - Immediately - AfterDelay - AfterCompletion description: > When stakeholder gets redirected after completing this action * afterSession - Redirect after signing session is ended, but before package is completed (only important for last signer). * immediately - Redirect as soon as possible. * afterDelay - Redirect after some delay (defined on frontend). * afterCompletion - Redirect after the package is completed. Only valid together with RedirectUrl - the API rejects RedirectType without it. BackButtonUrl: type: string format: url description: >- URL to which the end user is sent after pressing close session button example: https://homepage.example.test example: Type: signer SuppressNotifications: false Elements: - Type: signingField Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 SigningMethods: - manual - beid CreateApproverActor: title: Approver allOf: - $ref: '#/components/schemas/CreateActorBase' - type: object description: Determines whether a document is fit for signing properties: Type: enum: - Approver RedirectUrl: type: string format: url description: > Url to which the stakeholder is redirected after completing this action BackButtonUrl: type: string format: url description: >- URL to which the end user is sent after pressing close session button example: https://homepage.example.test example: Type: approver CreateFormFillerActor: title: Form filler allOf: - $ref: '#/components/schemas/CreateActorBase' - type: object description: Completes form fields on a document properties: Type: enum: - FormFiller RedirectUrl: type: string format: url description: > Url to which the stakeholder is redirected after completing this action RedirectType: type: string enum: - AfterSession - Immediately - AfterDelay - AfterCompletion description: > When stakeholder gets redirected after completing this action * afterSession - Redirect after signing session is ended, but before package is completed (only important for last signer). * immediately - Redirect as soon as possible. * afterDelay - Redirect after some delay (defined on frontend). * afterCompletion - Redirect after the package is completed. Only valid together with RedirectUrl - the API rejects RedirectType without it. Elements: type: array description: The actor's elements items: oneOf: - allOf: - $ref: '#/components/schemas/CreateCheckBoxField' - title: New check box field on a document properties: DocumentId: $ref: '#/components/schemas/Document.Id' - allOf: - $ref: '#/components/schemas/CreateTextBoxField' - title: New text box field on a document properties: DocumentId: $ref: '#/components/schemas/Document.Id' - allOf: - $ref: '#/components/schemas/CreateRadioGroup' - title: New radio group on a document properties: DocumentId: $ref: '#/components/schemas/Document.Id' - allOf: - $ref: '#/components/schemas/CreateComboBoxField' - title: New combo box field on a document properties: DocumentId: $ref: '#/components/schemas/Document.Id' - title: Existing element by Id properties: Id: $ref: '#/components/schemas/Element.Id' BackButtonUrl: type: string format: url description: >- URL to which the end user is sent after pressing close session button example: https://homepage.example.test example: Type: formFiller Elements: - Type: CheckBoxField Name: MyCheckBox1 ToolTipLabel: Tick me! IsRequired: false DefaultValue: true Location: Page: 1 Top: 200 Left: 200 Dimensions: Width: 10 Height: 10 CreateReceiverActor: title: Receiver allOf: - $ref: '#/components/schemas/CreateActorBase' - type: object description: Can download a copy of the fully signed document properties: Type: enum: - Receiver example: Type: receiver 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 CreateActorBase: type: object description: Parameters for creating an actor additionalProperties: false required: - Type properties: Type: $ref: '#/components/schemas/Actor.Type' SuppressNotifications: type: boolean default: false description: suppress the notifications for this actor RedirectUrl: type: string format: url description: > Url to which the stakeholder is redirected after completing this action 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": "" }`. 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: 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. Document.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A document's unique identifier Element.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: An element's unique identifier 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. InputType: $ref: '#/components/schemas/InputType' 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. CreateComboBoxField: title: Combo box field allOf: - $ref: '#/components/schemas/CreateFormFieldBase' - type: object description: > Available as of NSEV v8.5. Parameters for creating a combo box (dropdown) field. When `FieldId` references an existing combo box in the PDF, the options come from that PDF field and `Options` must not be provided; otherwise `Options` is required. properties: Type: enum: - ComboBoxField Options: type: array description: >- The combo box options. Required unless `FieldId` is set, in which case the options come from the PDF field and this must not be provided. 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, it must match the `ExportValue` (or the `DisplayLabel` when no `ExportValue` is set) of one of them, even when `AllowCustomInput` is true - and because option values are capped at 256 characters, the effective maximum length is 256. When `FieldId` is set, the value is applied to the PDF-sourced options as-is; when omitted, the PDF field's own default is kept. 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 Actor.Type: type: string description: >- The type of action an actor performs on a package, and the discriminator across the actor variants. - **FormFiller** - fills TextBoxField, CheckBoxField, RadioGroup and ComboBoxField (NSEV v8.5+) elements; does not sign or approve. Must be placed in the first process step. - **Approver** - approves a document as fit for signing, before any signer acts. Must be placed in the first process step (may share it with FormFillers). - **Signer** - signs one or more signing fields. - **Receiver** - receives a copy of the fully signed document; takes no action and must be placed in the last process step. enum: - Signer - Receiver - Approver - FormFiller 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 - ComboBoxField 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_|DD_)?(?:\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, ComboBoxField) - an `@`-prefixed text marker `@id_height_width#`, with `@id_TB_height_width#` for a text box, `@id_CB_height_width#` for a check box and `@id_DD_height_width#` for a combo box (NSEV v8.5+), 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 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 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. 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 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. 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' 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 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 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 responses: 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 ``` ````