> ## 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. # List actors > Retrieves all actors of the specified stakeholder. An actor represents a single action a stakeholder must take on the package; see Create actor for the actor types and their semantics. ## OpenAPI ````yaml /nsev/api-reference/openapi.yaml get /packages/{packageId}/stakeholders/{stakeholderId}/actors 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}/stakeholders/{stakeholderId}/actors: parameters: - $ref: '#/components/parameters/packageIdPathParam' - $ref: '#/components/parameters/stakeholderIdPathParam' get: tags: - Actors summary: List actors description: >- Retrieves all actors of the specified stakeholder. An actor represents a single action a stakeholder must take on the package; see Create actor for the actor types and their semantics. operationId: listActors responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Actor' example: - Type: approver SuppressNotifications: false Status: finished RedirectUrl: https://redirecttothis.test Result: CompletedBy: Email: john@doe.test CompletedDate: 2020-01-24T09:24:13+0000 - Type: formFiller SuppressNotifications: false Status: available Elements: - Id: 00000000-0000-0000-0000-000000000000 ActorId: 00000000-0000-0000-0000-000000000000 Type: TextBoxField Name: TextBox1 Label: Empty textbox IsRequired: false IsMultiline: false DefaultValue: null CharLimit: 115 Location: Page: 1 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 ExternalReference: my_checkboxfield - Id: 00000000-0000-0000-0000-000000000001 ActorId: 00000000-0000-0000-0000-000000000000 Type: CheckBoxField Name: CheckBox1 Label: To be checked IsRequired: true Checked: null DefaultValue: false Location: Page: 1 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 ExternalReference: my_checkboxfield Links: - https://fill.test/package/1234 - Type: signer SuppressNotifications: false Status: available Elements: - Id: 00000000-0000-0000-0000-000000000000 ActorId: 00000000-0000-0000-0000-000000000000 Type: signingField Location: Page: 2 Top: 200 Left: 200 Dimensions: Width: 200 Height: 200 ExternalReference: my_signingfield SigningMethods: - manual LegalNotice: Text: Read and approved Links: - https://sign.test/package/1234 RedirectUrl: https://redirecttothis.test '401': $ref: '#/components/responses/UnAuthorized' '404': description: Target package or stakeholder with id could not be found content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/PackageNotFoundError' - $ref: '#/components/schemas/StakeholderNotFoundError' components: parameters: packageIdPathParam: name: packageId in: path required: true description: The target package's unique identifier schema: $ref: '#/components/schemas/Package.Id' stakeholderIdPathParam: name: stakeholderId in: path required: true description: The target stakeholder's unique identifier schema: $ref: '#/components/schemas/Stakeholder.Id' schemas: Actor: oneOf: - $ref: '#/components/schemas/SignerActor' - $ref: '#/components/schemas/ReceiverActor' - $ref: '#/components/schemas/ApproverActor' - $ref: '#/components/schemas/FormFillerActor' discriminator: propertyName: Type mapping: Signer: $ref: '#/components/schemas/SignerActor' Receiver: $ref: '#/components/schemas/ReceiverActor' Approver: $ref: '#/components/schemas/ApproverActor' FormFiller: $ref: '#/components/schemas/FormFillerActor' example: Type: signer Status: available Elements: - Id: 00000000-0000-0000-0000-000000000000 Type: signingField Location: Page: 2 Top: 250 Left: 250 Dimensions: Width: 230 Height: 230 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 StakeholderNotFoundError: title: Stakeholder not found allOf: - $ref: '#/components/schemas/NotFoundError' example: ErrorCode: Stakeholder.NotFound:00000000-0000-0000-0000-000000000000 ErrorMessage: >- The stakeholder with id '00000000-0000-0000-0000-000000000000' could not be found Package.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A package's unique identifier Stakeholder.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: A stakeholder's unique identifier SignerActor: title: Signer allOf: - $ref: '#/components/schemas/ActorBase' - type: object description: Signs one or more signing fields properties: Type: enum: - Signer Result: $ref: '#/components/schemas/SignerActorResult' Elements: type: array description: The actor's elements items: oneOf: - $ref: '#/components/schemas/SigningField' 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 ReceiverActor: title: Receiver allOf: - $ref: '#/components/schemas/ActorBase' - type: object description: Can download a copy of the fully signed document properties: Type: enum: - Receiver ApproverActor: title: Approver allOf: - $ref: '#/components/schemas/ActorBase' - 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, always as soon as possible BackButtonUrl: type: string format: url description: >- URL to which the end user is sent after pressing close session button example: https://homepage.example.test Result: $ref: '#/components/schemas/ApproverActorResult' FormFillerActor: title: Form filler allOf: - $ref: '#/components/schemas/ActorBase' - type: object description: Completes one or more form fields properties: Type: enum: - FormFiller Elements: type: array description: The actor's elements items: oneOf: - $ref: '#/components/schemas/CheckBoxField' - $ref: '#/components/schemas/TextBoxField' - $ref: '#/components/schemas/RadioGroup' - $ref: '#/components/schemas/ComboBoxField' 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 Result: $ref: '#/components/schemas/FormFillerActorResult' 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 Guid: title: GUID type: string description: A globally unique identifier format: guid example: 00000000-0000-0000-0000-000000000000 ActorBase: allOf: - type: object description: An action to be performed additionalProperties: false properties: Id: $ref: '#/components/schemas/Actor.Id' Type: $ref: '#/components/schemas/Actor.Type' Status: $ref: '#/components/schemas/Actor.Status' SuppressNotifications: type: boolean default: false description: suppress the notifications for this actor - type: object properties: ActionUrls: type: array items: type: object description: links to interact with the package for this stakeholder properties: Email: type: string format: email description: >- email address of the person stakeholder that will have to perform this action Url: type: string format: url description: >- link to interact with the package for this person stakeholder Type: type: string description: Type of action url enum: - Approver - FormFiller - Signer - Preview - Download - Archive - type: object properties: Links: type: array description: Only present when the actor's stakeholder is a person. items: type: string format: url description: links to interact with the package for this person stakeholder MemberLinks: type: array description: >- Only present when the actor's stakeholder is a group or contact group. items: type: object description: links to interact with the package for this group stakeholder properties: Email: type: string format: email description: >- email address of the member that will have to perform this action Link: type: string format: url description: >- link to interact with the package for this stakeholder member SignerActorResult: allOf: - $ref: '#/components/schemas/ActorResult' - type: object properties: RejectReason: type: string description: why a signer rejected signing 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' ApproverActorResult: allOf: - $ref: '#/components/schemas/ActorResult' - type: object properties: RejectReason: type: string description: why an approver rejected the package 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 InputType: $ref: '#/components/schemas/InputType' 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' ComboBoxField: title: Combo box field allOf: - $ref: '#/components/schemas/ElementBase' - $ref: '#/components/schemas/FormFieldBase' - type: object description: | Available as of NSEV v8.5. A combo box (dropdown) field. properties: Location: $ref: '#/components/schemas/Element.Location' Dimensions: $ref: '#/components/schemas/Element.Dimensions' 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 FormFillerActorResult: allOf: - $ref: '#/components/schemas/ActorResult' - type: object properties: RejectReason: type: string description: why a form filler rejected the package 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.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: This actor's unique identifier 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 Actor.Status: type: string description: >- The status of an actor's action. - **Draft** - the package is still in draft; the action is not yet active. - **Waiting** - the action is waiting for an earlier process step to complete. - **Available** - the action is ready to be performed. - **InProgress** - the action is being performed. - **Failed** - the action failed. - **Finished** - the action was completed. - **Rejected** - the actor rejected the document. - **Skipped** - the action was skipped (for example via skip approvers/signers). enum: - Draft - Waiting - Available - InProgress - Failed - Finished - Rejected - Skipped ActorResult: type: object description: The result of a completed action properties: CompletedBy: type: object properties: Email: type: string format: email example: john@doe.test VerifiedName: type: string nullable: true example: John Doe description: >- The name of a person taken from third party authentication services. CompletedDate: type: string format: dateTime 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 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 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 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 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 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 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' 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 Element.Id: allOf: - $ref: '#/components/schemas/Guid' - type: string description: An element's unique identifier 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 Element.Status: type: string description: The status of a document element enum: - Pending - InProgress - Rejected - Failed - Finished - Refused 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. responses: UnAuthorized: description: Caller is unauthorized to perform this operation 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 ``` ````