Skip to content

Send Your First Envelope

This guide walks you through sending a signing request using the NSE API v1. By the end you will have created an envelope, uploaded a document, added a signer, placed a signature field, and sent the envelope — all via API.

Prerequisites

  • A valid JWT Bearer token or Personal Access Token
  • Your organization ID (organizationId)
  • A document ready to upload

Step 1 — Create an Envelope

Start by creating an envelope. This is the container for your documents and recipients. It is created in draft status and stays editable until you send it.

In most integrations you will at minimum give it a name and set an expiration. Here we use a relative expiration — 14 days after sending (expressed in seconds).

POST /api/v1/organizations/{organizationId}/envelopes
{
  "name": "Lease Agreement",
  "expiration": {
    "mode": "relative",
    "afterSendInSeconds": 1209600
  }
}

Response 201 Created

{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890"
}

Save the returned id — this is your envelopeId for every subsequent call.


Step 2 — Upload a Document

Upload the PDF that your recipient will sign. This endpoint uses multipart/form-data, not JSON.

Note: The max file size is 10MB and an envelope can max have 10 documents.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data
FieldTypeDescription
filebinaryThe PDF file to attach

Response 201 Created

{
  "id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}

Save the returned id — this is your fileId, used when placing the signature field.


Step 3 — Add a Signing Stage

A stage represents a step in the signing workflow. Recipients in the same stage sign in parallel; stages execute in order. For this example, one stage with one signer is enough.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
{
  "name": "Signers",
  "requiredRecipientCompletions": 1,
  "type": "signer"
}

Response 201 Created

{
  "id": "5c367bac-1234-1234-1234-08f3025e28ab"
}

Save the returned id — this is your stageId.


Step 4 — Add a Recipient

Add the person who will sign the document to the stage you just created.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
{
  "givenName": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "notificationChannels": [
    "email"
  ]
}

Response 201 Created

{
  "id": "4e861e0f-1234-1234-1234-58bd9928b4a8"
}

Save the returned id — this is your recipientId, used when placing the signature field.


Step 5 — Place a Signature Field

Add now all the fields which should appear on the document and add who should sign it. This call fully replaces all tasks for the file, so send the complete list each time.

Each task wraps a field definition with the recipientId and a sortOrder.

PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks
{
  "tasks": [
    {
      "field": {
        "fieldType": "Signature",
        "id": "field-001",
        "page": 1,
        "positionX": 100,
        "positionY": 650,
        "width": 200,
        "height": 60,
        "allowedSignatureTypes": [
          { "signatureType": "ClickToSignSignature" },
          { "signatureType": "DrawToSignSignature" }
        ]
      },
      "recipientId": "4e861e0f-1234-1234-1234-58bd9928b4a8",
      "sortOrder": 1
    }
  ]
}

A few things worth noting:

  • positionX / positionY are the coordinates of the field's top-left corner on the page.
  • allowedSignatureTypes controls which signing methods the recipient can choose. If you leave it null, the organization defaults apply.
  • sortOrder sets the sequence in which fields are presented to the signer. Response 204 No Content

Step 6 — Send the Envelope

Once everything is configured, send the envelope. This transitions the envelope from draft to sent and triggers the invitation email to your recipient.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send

No request body required.

Response 204 No Content


Step 7 — Check the Envelope Status

Poll this endpoint to track progress.

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}

Response 200 OK

{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890",
  "name": "Lease Agreement",
  "status": "completed",
  "sentAt": "2026-04-20T10:05:00Z"
  ...
}

Step 8 — Download the Signed Document

Once the envelope is completed, retrieve the signed file and the audit trail.

List what is available:

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts
{
  "artifacts": [
    {
      "id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
      "name": "LeaseAgreement.pdf",
      "type": "CompletedFile"
    },
    {
      "id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
      "name": "Audit Trail.pdf",
      "type": "AuditTrail"
    }
  ]
}

Download a specific artifact:

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}

Returns the file as a binary stream (application/pdf).


What's Next

This guide covered the essential flow. The full API reference describes additional options available at each step, including:

  • Envelope: automatic reminders, absolute expiration dates
  • Stages: parallel signing, approval-only stages (Approver), carbon copy (CarbonCopy)
  • Recipients: SMS/OTP authentication, access codes, QES certificate configuration
  • Fields: text inputs, checkboxes, dropdowns, read confirmations, and more