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.
- A valid JWT Bearer token or Personal Access Token
- Your organization ID (
organizationId) - A document ready to upload
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.
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| Field | Type | Description |
|---|---|---|
file | binary | The 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.
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.
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.
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/positionYare the coordinates of the field's top-left corner on the page.allowedSignatureTypescontrols which signing methods the recipient can choose. If you leave itnull, the organization defaults apply.sortOrdersets the sequence in which fields are presented to the signer. Response204 No Content
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}/sendNo request body required.
Response 204 No Content
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"
...
}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).
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