Skip to content

API Reference

The Namirial Sign Enterprise API (v1) is a RESTful API that lets you create, manage, and monitor electronic signature workflows programmatically. You can use it to integrate NSE into your own applications, automate envelope dispatching, or build custom signing portals.

The interactive API specification is available below — use it to explore endpoints, inspect request and response schemas, and try calls directly.


Base URL

All API endpoints are relative to your NSE instance base URL:

E.g.

https://demo-eu-ie1-api.namirialsign.com/api/

Most of the endpoint includes organizationId as a required path parameter (make sure to have it available whenever using the api). This is the identifier of the organization in your NSE instance that owns the resource being operated on.


Principles of API v1

  • Full REST semantics — uses GET, POST, PUT, PATCH, and DELETE verbs according to standard REST conventions.
  • Organization-scoped resources — all resources beside reference data are scoped under /organizations/{organizationId}/.
  • Stage-based workflow — signing workflows are modelled as ordered Stages. Recipients within the same stage sign in parallel; stages are processed sequentially in sort order.
  • Separation of structure and content — files, stages, and recipients are managed as independent sub-resources of an envelope or template, allowing fine-grained control over each part of the workflow.
  • Artifacts for completed documents — once an envelope is completed, signed documents and the audit trail are accessible as Artifacts.

Authentication

API authentication uses OAuth 2.0 Client Credentials via MyNamirial as the Identity Provider.

Setup

  1. Create an IdP application (Service Account).
  2. Note the Client ID and Client Secret assigned to the application.

Note: The creation of an IdP in MyNamirial and the release of ClientID and ClientSecret can be completed in the UI in the section for Service Accounts. For more information see: Service Account

Obtaining a token

Use the Client Credentials grant to obtain a JWT Bearer token.

Personal Access Token

Additionally a Personal access token can be created in order to use the API. For more information see: Access Token. Add as headers the "Personal-Access-Token" and the token retrieved as value.

Using the token

Include the token as a Bearer token in the Authorization header of every API request:

Authorization: Bearer <access_token>

Unauthenticated or expired-token requests return 401 Unauthorized.


Core Concepts

Envelope

An envelope represents a single signature request. It contains one or more documents (files), a signing workflow (stages), and envelope options such as name, expiration date, and reminder configuration.

Envelope lifecycle:

StatusDescription
DraftCreated but not yet sent. All configuration can be modified.
InProgressSent to recipients. The signing workflow is in progress.
CompletedAll recipients have finished their activities. Artifacts are available for download.
CanceledManually canceled. No further activity is possible.
ExpiredThe expiration date was reached before completion. Can be resumed with a new date.
RejectedThe envelope was rejected by one or more recipients.

Template

A template is a reusable envelope configuration — pre-loaded with documents, stages, recipients, and field placements. Creating an envelope from a template copies the full configuration into a new Draft envelope, which can be customised before sending.

Stage

A stage represents one step in the signing workflow. Each stage contains one or more recipients who act in parallel. Stages are processed sequentially in ascending sortOrder. Use requiredRecipientCompletions to allow a stage to advance when a minimum number of recipients (out of the total) have completed their activity — useful for group signing scenarios.

Recipient

A recipient is a person assigned to a stage. Each recipient has contact details (email, name, phone), a notification channel (Email, SMS, WhatsApp, or None), a language preference, optional authentication requirements (access code, SMS OTP, OAuth), and an optional signature configuration (signature type and any required pre-filled data).

File and Tasks

A file is a document attached to an envelope or template. Tasks are the interactive elements assigned to recipients — signature fields, text inputs, checkboxes, dropdowns, attachment requests, and confirmation reads. Most tasks are positioned on a specific page of a file, but some (such as confirmation reads) operate at the file or page level without a fixed position.

Artifact

Once an envelope reaches Completed status, its output files become available as Artifacts. There are two artifact types: CompletedFile (the signed document) and AuditTrail (the full event log as a PDF).


Supported Signature Types

TypeDescription
ClickToSignSignatureSimple click-to-confirm signature — no cryptographic certificate.
DrawToSignSignatureFreehand drawn signature captured in the browser or on a touch device.
TypeToSignSignatureSignature created by typing the recipient's name in a chosen font.
LocalCertificateSignatureSignature using a certificate installed on the recipient's local device.
DisposableCertificateSignatureSignature using a short-lived (one-time) qualified certificate generated at signing time.
BiometricSignatureSignature captured via a biometric tablet (pen pressure and dynamics).
RemoteCertificateSignatureSignature using a remote qualified certificate (requires userId and deviceId).
OneTimePasswordSignatureSignature confirmed via SMS OTP sent to the recipient's phone number.
AutomaticSignatureSignature applied without any interaction needed
PluginSignatureSignature delegated to a custom signing plugin configured on the instance.

Error Handling

All error responses follow a consistent structure:

{
  "errors": [
    {
      "errorId": "string",
      "field": "string",
      "message": "string",
      "messageEn": "string",
      "additionalData": {}
    }
  ]
}
HTTP StatusMeaning
200 OKRequest succeeded.
201 CreatedResource was created. The new resource ID is returned in the response body.
204 No ContentRequest succeeded with no response body (update or delete).
400 Bad RequestThe request is invalid or malformed.
401 UnauthorizedAuthentication is missing or the token is expired.
403 ForbiddenThe authenticated user does not have permission to access this resource.
404 Not FoundThe requested resource does not exist.
422 Unprocessable EntityThe request is valid but violates a business rule.
500 Internal Server ErrorAn unexpected error occurred on the server.

Typical Integration Workflow

A typical integration for sending a signature request follows these steps:

  1. Create an envelope — POST /organizations/{organizationId}/envelopes
  2. Upload a document — POST /organizations/{organizationId}/envelopes/{envelopeId}/files
  3. Add a signing stage — POST /organizations/{organizationId}/envelopes/{envelopeId}/stages
  4. Add a recipient to the stage — POST /organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
  5. Place field tasks on the document — PUT /organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks
  6. Send the envelope — POST /organizations/{organizationId}/envelopes/{envelopeId}/send
  7. Check the envelope — GET /organizations/{organizationId}/envelopes/{envelopeId}
  8. Download artifacts — GET /organizations/{organizationId}/envelopes/{envelopeId}/artifacts

To create from a template, replace steps 1–5 with:

  1. Create an envelope from a template — POST /organizations/{organizationId}/templates/{templateId}/create-envelope
  2. Optionally update recipients or files in the draft, then proceed to send.

API Specification

The full interactive API specification is available on the Swagger UI of your NSE instance. Contact your Namirial representative to obtain the correct URL for your environment.

The DEMO SwaggerUI is available at this URL: https://demo-eu-ie1-api.namirialsign.com/api/swagger/index.html