instasign

Instasign Node.js SDK

The Instasign Node.js SDK provides convenient access to the Instasign Service from applications written in server-side JavaScript or TypeScript. It is designed to simplify document signing workflows by providing a high-level, promise-based API for creating envelopes, managing sign requests, and verifying webhooks.

[!CAUTION] Security Warning: While this library can technically be used in client-side (frontend) applications, it is strongly discouraged for security reasons. Using the SDK on the frontend requires you to expose your Instasign API key, which could be stolen by anyone visiting your site. For production applications, always perform Instasign API calls from a secure server-side environment.

Installation

Install the package with:

npm install instasign

Usage

The package needs to be configured with your account's API key. You can also provide Parse Server configuration if you are using a custom instance.

import { Instasign } from 'instasign';

const instasign = new Instasign({
  apiKey: 'your_api_key',
  restApiKey: 'your_parse_rest_api_key', // Optional
  serverUrl: 'https://api.instasign.io', // Optional: Your server URL
  appId: 'your_app_id', // Optional: Your Parse App ID
  webhookTolerance: 300 // default is 300 seconds
});

Envelopes

Envelopes are containers for one or more documents that need to be signed.

// Create an envelope
const envelope = await instasign.envelopes.create({
  name: 'Service Agreement',
  description: 'Please sign the attached document',
});

// List envelopes with full type support for nested objects
const envelopes = await instasign.envelopes.list({
  status: 'pending',
  orderBy: 'createdAt',
  orderDirection: 'desc'
});

// Retrieve an envelope by ID
const envelope = await instasign.envelopes.get('envelope_id_here');

// Update envelope metadata
await instasign.envelopes.updateMetadata({
  envelopeId: 'envelope_id_here',
  metadata: { customField: 'value' }
});

// Add sign requests to an envelope
await instasign.envelopes.addAll({
  envelopeId: 'envelope_id_here',
  signRequests: [
    {
      filename: 'contract.pdf',
      base64File: '...',
      signatureType: 'advanced', // 'otp' | 'advanced' | 'qualified' — defaults to 'otp'
    }
  ]
});

// Delete an envelope
await instasign.envelopes.delete('envelope_id_here');

Sign Requests

Manage individual signature requests.

// Create a sign request
const signRequest = await instasign.signRequests.create({
  filename: 'contract.pdf',
  base64File: '...', // base64 encoded file content
  signatureType: 'otp', // 'otp' | 'advanced' | 'qualified' — defaults to 'otp'
});

// Retrieve file data
const fileData = await instasign.signRequests.get('request_id_here');

// Complete a sign request
await instasign.signRequests.complete({
  requestId: 'request_id_here',
  signedFileDataBase64: '...'
});

Webhooks

Instasign can send webhook events to your server. Use the webhooks resource to verify signature headers securely.

const payload = req.body; // Raw request body
const sig = req.headers['x-instasign-signature'];
const endpointSecret = 'secret_key';

try {
  const event = instasign.webhooks.constructEvent(payload, sig, endpointSecret);
  // Handle the event (fully typed)
  console.log(event.type); // e.g., 'envelope.completed'
} catch (err) {
  console.error(`Webhook Error: ${err.message}`);
  res.status(400).send(`Webhook Error: ${err.message}`);
}

TypeScript Support

This library is built with TypeScript and provides industry-standard type definitions auto-generated from the Instasign OpenAPI schema. Every method in the SDK is strictly typed, including:

• Enums: Fields like status, signatureType, orderBy, and orderDirection use string union types.
• Nested Objects: Complex structures like the signRequests array inside an envelope are fully typed.
• Dates: Automatic mapping of ISO date strings for createdAt, updatedAt, and expirationDate.

Configuration Options

Option	Type	Description
apiKey	string	Required. Your Instasign Dashboard API Key (passed in x-api-key header).
restApiKey	string	Optional. Your Parse REST API Key (passed in X-Parse-REST-API-KEY header).
serverUrl	string	Optional. Base URL for the Parse Server (defaults to Back4App).
appId	string	Optional. Your Parse Application ID.
webhookTolerance	number	Optional. Allowed time drift for webhook signatures in seconds (default: 300).

License

Apache-2.0