Skip to content

Latest commit

 

History

History
1112 lines (919 loc) · 34.3 KB

README.md

File metadata and controls

1112 lines (919 loc) · 34.3 KB
Raw

The Official SignNow API client v1.8.2

SignNow Node.js REST API Wrapper

License Node version support Snyk vulnerabilities for npm package NPM package version Twitter Follow

Table of Contents

  1. About SignNow
  2. API Contact Information
  3. API and Application
  4. Installation
  5. Documentation
  6. Examples
  7. Unit Tests
  8. License
  9. Additional Contact Information

About SignNow

SignNow is a powerful web-based e-signature solution that streamlines the signing process and overall document flow for businesses of any size. SignNow offers SaaS as well as public and private cloud deployment options using the same underlying API. With SignNow you can easily sign, share and manage documents in compliance with international data laws and industry-specific regulations. SignNow enables you to collect signatures from partners, employees and customers from any device within minutes.

API Contact Information

If you have questions about the SignNow API, please visit https://docs.signnow.com or email [email protected].

See additional contact information at the bottom.

API and Application

Resources Sandbox Production
API: api-eval.signnow.com:443 api.signnow.com:443
Application: https://app-eval.signnow.com https://app.signnow.com
Entry page: https://eval.signnow.com

Installation

@signnow/api-client supports node.js v6.4.0 or later.

To install the latest version of @signnow/api-client run:

npm install @signnow/api-client

Documentation

See API reference in our Documentation.

Examples

To run the examples you will need an API key. You can get one here https://www.signnow.com/api. For a full list of accepted parameters, refer to the SignNow REST Endpoints API guide: https://docs.signnow.com.

Every resource is accessed via your api client instance:

const api = require('@signnow/api-client')({
  credentials: 'ENCODED_CLIENT_CREDENTIALS',
  production: false, // if false uses eval server
});

Every resource returns two parameters. The first param contains any errors and the second contains the results.

User

Create a User

By default verification email is not sent. To send it set verifyEmail option to true.

api.user.create({
  email: '[email protected]',
  password: 'your password',
  first_name: 'John',
  last_name: 'Wayne',
  number: '123-456-789',
  options: { verifyEmail: true } // false by default
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Send Verification Email

api.user.verifyEmail({
  email: '[email protected]',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Send Verification Email

api.user.verifyEmail({
  email: '[email protected]',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Retrieve User Information

api.user.retrieve({
  token: 'your auth token',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

OAuth 2.0

Request Access Token

api.oauth2.requestToken({
  username: 'username',
  password: 'password',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Verify Access Token

api.oauth2.verify({
  token: 'your auth token',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Refresh Access Token

api.oauth2.refreshToken({
  refresh_token: 'your refresh token',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Document

Retrieve a List of the User’s Documents

api.document.list({
  token: 'your auth token',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Retrieve a Document Resource

api.document.view({
  token: 'your auth token',
  id: 'document id',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Download a Collapsed Document

By default document is downloaded without history or attachments. To download it with history set withHistory option to true. To download it with attachments set withAttachments option to true.

api.document.download({
  token: 'your auth token',
  id: 'document id',
  options: { 
    withAttachments: true, // false by default
    withHistory: true, // false by default
  },
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Upload Document

api.document.create({
  token: 'your auth token',
  filepath: 'path to file',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Upload File & Extract Fields

api.document.fieldextract({
  token: 'your auth token',
  filepath: 'path to file',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Update Document (add fields)

const fields = {
  texts: [
    {
      size: 8,
      x: 61,
      y: 72,
      page_number: 0,
      font: 'Arial',
      data: 'sample text',
      line_height: 9.075,
    },
  ],
}

api.document.update({
  token: 'your auth token',
  id: 'document id',
  fields,
}, (err, res) => {
  // handle error or process response data
});

More: Add signature field example, Add text field example, CLI applet

Create Invite to Sign a Document

const fieldInvite = {
  from: 'EMAIL_OF_SENDER',
  to: [
    {
      email: 'EMAIL_OF_SIGNER',
      role: 'Signer 1',
      order: 1,
      reassign: '0',
      decline_by_signature: '0',
      reminder: 4,
      expiration_days: 27,
      subject: 'Field invite Signer1',
      message: 'Message',
    },
  ],
};

api.document.invite({
  data: {
    ...fieldInvite,
  },
  id: 'DOCUMENT_ID_GOES_HERE',
  token: 'YOUR_AUTH_TOKEN',
}, (err, res) => {
  // handle error or process response data
});

More: Invite to sign example, Invite with payment request example, CLI applet

Create Free Form Invite

api.document.invite({
  token: 'your auth token',
  id: 'document id',
  data: {
    from: 'email address',
    to: 'email address',
  },
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Cancel Field Invite to Sign a Document

api.document.cancelFieldInvite({
  token: 'your auth token',
  id: 'document id',
}, (err, res) => {
  // handle error or process response data
});

Cancel Free Form Invite

api.document.cancelFreeFormInvite({
  token: 'your auth token',
  id: 'id of invite',
}, (err, res) => {
  // handle error or process response data
});

Create a One-time Use Download URL

api.document.share({
  token: 'your auth token',
  id: 'document id',
}, (err, res) => {
  // handle error or process response data
});

More: Full example

Merge Existing Documents

By default original documents are not removed after merging. To remove original documents set removeOriginalDocuments option to true.

api.document.merge({
  token: 'your auth token',
  name: 'the merged doc',
  document_ids: [
    '84a18d12bf7473ea3dd0e4dd1cdcded6ba6281aa',
    'a71d963c49f33176e90c5827069c422616b1500c',
  ],
  options: {
    removeOriginalDocuments: true, // false by default
  },
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Get Document History

api.document.history({
  token: 'your auth token',
  id: 'document id',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Remove Document

By default document invites are not cancelled during deletion. To cancel all document invites set cancelInvites option to true.

api.document.remove({
  token: 'your auth token',
  id: 'document id',
  options: {
    cancelInvites: true, // false by default
  },
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

Links

Create Signing Link

api.link.create({
  token: 'your auth token',
  document_id: 'document or template id',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Enumerations

Add Enumeration Field to a Document

api.enumerations.addField({
  token: 'your auth token',
  document_id: 'document id',
  x: 150,
  y: 200,
  width: 200,
  height: 50,
  page_number: 0,
  role: 'buyer',
  required: true,
  label: 'Clothing Brand',
}, (err, res) => {
  // handle error or process response data
});

Add Enumeration Options to the Field

api.enumerations.addOptions({
  token: 'your auth token',
  enumeration_options: [
    {
      enumeration_id: '8a3501896160b12d4ef7507a81b2f0998b8137b1',
      data: 'Active',
    },
    {
      enumeration_id: '8a3501896160b12d4ef7507a81b2f0998b8137b1',
      data: 'Old Navy',
    },
    {
      enumeration_id: '8a3501896160b12d4ef7507a81b2f0998b8137b1',
      data: 'Volcom',
    },
  ],
}, (err, res) => {
  // handle error or process response data
});

Template

Create a Template

By default original document is not removed after template creation. To remove original document set removeOriginalDocument option to true.

api.template.create({
  token: 'your auth token',
  document_id: 'document id',
  document_name: 'my template',
  options: {
    removeOriginalDocument: true, // false by default
  },
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Create a Document from a Template

api.template.duplicate({
  token: 'your auth token',
  id: 'document id',
  name: 'my template',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Create Invite to Sign a Template

const fieldInvite = {
  from: 'EMAIL_OF_SENDER',
  to: [
    {
      email: 'EMAIL_OF_SIGNER',
      role: 'Signer 1',
      order: 1,
      reassign: '0',
      decline_by_signature: '0',
      reminder: 4,
      expiration_days: 27,
      subject: 'Field invite Signer1',
      message: 'Message',
    },
  ],
};

api.template.invite({
  data: {
    ...fieldInvite,
  },
  id: 'TEMPLATE_ID_GOES_HERE',
  token: 'YOUR_AUTH_TOKEN',
}, (err, res) => {
  // handle error or process response data
});

More: Full one role example, Full two roles example, CLI applet

Create Free Form Invite from Template

api.template.invite({
  token: 'YOUR_AUTH_TOKEN',
  id: 'TEMPLATE_ID_GOES_HERE',
  data: {
    from: 'EMAIL_OF_SENDER',
    to: 'EMAIL_OF_SIGNER',
  },
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Remove Template

api.template.remove({
  token: 'your auth token',
  id: 'template id',
}, (err, res) => {
  // handle error or process response data
});

More: CLI applet

View Routing Details

api.template.getRoutingDetails({
  token: 'your auth token',
  id: 'template id',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Update Routing Details

const routingDetails = {
  template_data: [
    {
      default_email: '',
      inviter_role: false,
      name: 'Signer 1',
      role_id: 'SIGNER 1 ROLE ID',
      signing_order: 1,
      decline_by_signature: true,
    },
    {
      default_email: '[email protected]',
      inviter_role: false,
      name: 'Signer 2',
      role_id: 'SIGNER 2 ROLE ID',
      signing_order: 2,
    },
  ],
  cc: [
    '[email protected]',
    '[email protected]',
  ],
  cc_step: [
    {
      email: '[email protected]',
      step: 1,
      name: 'CC 1',
    },
    {
      email: '[email protected]',
      step: 2,
      name: 'CC 2',
    },
  ],
  invite_link_instructions: 'Invite link signing instruction',
};

api.template.updateRoutingDetails({
  data: routingDetails,
  token: 'your auth token',
  id: 'template id',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Folder

Returns a list of folders

api.folder.list({
  token: 'your auth token',
}, (err, res) => {
  // handle error or process response data
});

Returns a list of documents inside a folder

Filters Values
signing-status waiting-for-me, waiting-for-others, signed, pending
document-updated new Date()
document-created new Date()
Sort Values
document-name asc/desc
updated asc/desc
created asc/desc 
api.folder.documents({
  token: 'your auth token',
  id: 'folder id',
  filter: [
    {
      'signing-status': 'pending',
    },
  ],
  sort: {
    'document-name': 'asc',
  },
}, (err, res) => {
  // handle error or process response data
});

Document Group

Create Document Group

api.documentGroup.create({
  token: 'your auth token',
  group_name: 'my document group name',
  ids: [
    // put document or template IDs here
    '84a18d12bf7473ea3dd0e4dd1cdcded6ba6281aa',
    'a71d963c49f33176e90c5827069c422616b1500c',
  ],
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

View Document Group

api.documentGroup.view({
  token: 'Your auth token',
  id: 'Document Group ID',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Create Invite to Sign a Document Group

const data = {
  invite_steps: [
    {
      order: 1,
      invite_emails: [
        {
          email: 'Email of Signer 1',
          subject: 'Signer 1 Needs Your Signature',
          message: 'Signer 1 invited you to sign Document 1',
          expiration_days: 30,
          reminder: 0,
        },
      ],
      invite_actions: [
        {
          email: 'Email of Signer 1',
          role_name: 'Signer 1',
          action: 'sign',
          document_id: 'Document 1 ID',
          allow_reassign: '0',
          decline_by_signature: '0',
        },
      ],
    },
    {
      order: 2,
      invite_emails: [
        {
          email: 'Email of Signer 2',
          subject: 'Signer 2 Needs Your Signature',
          message: 'Signer 2 invited you to sign Document 2',
          expiration_days: 30,
          reminder: 0,
        },
      ],
      invite_actions: [
        {
          email: 'Email of Signer 2',
          role_name: 'Signer 2',
          action: 'sign',
          document_id: 'Document 2 ID',
          allow_reassign: '0',
          decline_by_signature: '0',
        },
      ],
    },
  ],
};

api.documentGroup.invite({
  token: 'your auth token',
  id: 'Document Group ID',
  data,
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Cancel Invite to Sign a Document Group

api.documentGroup.cancelInvite({
  token: 'your auth token',
  id: 'Document Group ID',
  inviteId: 'Document Group invite ID'
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Download Document Group

By default Document Group is downloaded without history as .zip archive with PDF files. To download it as a signle merged PDF set type to merged. To download document group with history set with_history to after_each_document or after_merged_pdf.

api.documentGroup.download({
  token: 'your auth token',
  id: 'document group ID',
  type: 'merged', // 'zip' by default
  with_history: 'after_each_document', // 'no' by default
}, (err, res) => {
  // handle error or process response data
});

More: Zipped Download Example, Merged Download Example, CLI applet

Document Group Template

Create Document Group Template

const routing_details = {
  invite_steps: [
    {
      order: 1,
      invite_emails: [
        {
          email: 'Email of Signer 1',
          subject: 'Signer 1 Needs Your Signature',
          message: 'Signer 1 invited you to sign Document 1',
          expiration_days: 30,
          reminder: 0,
          hasSignActions: true,
          allow_reassign: '0',
        },
      ],
      invite_actions: [
        {
          email: 'Email of Signer 1',
          role_name: 'Signer 1',
          action: 'sign',
          document_id: 'b6f4f61a5662c5c4385b02421397b76dc6d9c8af',
          document_name: 'Document 1',
          allow_reassign: '0',
          decline_by_signature: '0',
        },
      ],
    },
    {
      order: 2,
      invite_emails: [
        {
          email: 'Email of Signer 2',
          subject: 'Signer 2 Needs Your Signature',
          message: 'Signer 2 invited you to sign Document 2',
          expiration_days: 30,
          reminder: 0,
          hasSignActions: true,
          allow_reassign: '0',
        },
      ],
      invite_actions: [
        {
          email: 'Email of Signer 2',
          role_name: 'Signer 2',
          action: 'sign',
          document_id: '14f02aac643770f22a384fe4e7a6b1ed6d15a9b8',
          document_name: 'Document 2',
          allow_reassign: '0',
          decline_by_signature: '0',
        },
      ],
    },
  ],
  include_email_attachments: 0,
};

api.documentGroupTemplate.create({
  token: 'your auth token',
  template_ids: [
      '84a18d12bf7473ea3dd0e4dd1cdcded6ba6281aa',
      'a71d963c49f33176e90c5827069c422616b1500c',
    ],
  template_group_name: 'Document group template name',
  routing_details,
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

View Document Group Template

api.documentGroupTemplate.view({
  token: 'Your auth token',
  id: 'Document Group Template ID',
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Create Invite to Sign a Document Group Template

api.documentGroupTemplate.invite({
  token: 'Your auth token',
  id: 'Document Group Template ID'
}, (err, res) => {
  // handle error or process response data
});

More: Full example, CLI applet

Webhook

Returns a list of Webhooks

signnow.webhook.list({
  token: 'your auth token',
}, (err, res) => {
  // handle error or process response data
});

Create a Webhook

Events Description
document.create Webhook is triggered when a document is uploaded to users account in SignNow
document.update Webhook is triggered when a document is updated (fields added, text added, signature added, etc.)
document.delete Webhook is triggered when a document is deleted from
invite.create Webhook is triggered when an invitation to a SignNow document is created.
invite.update Webhook is triggered when an invite to SignNow document is updated. Ex. A signer has signed the document. 
api.webhook.create({
  token: 'your auth token',
  event: 'document.create',
  callback_url: 'http://www.domain.com/path',
}, (err, res) => {
  // handle error or process response data
});

Embedded

Create embedded signing invites for a document without sending emails

signnow.embedded.createInvite({
  token: 'access token',
  document_id: 'document id',
  invites: [
    {
      email: 'email of signer',
      role_id: 'role id',
      order: 1,
      auth_method: 'password',
    },
  ],
}, (err, res) => {
  // handle error or process response data
});

Creates a link for the embedded invite.

signnow.embedded.generateInviteLink({
  token: 'access token',
  document_id: 'document id',
  field_invite_unique_id: 'field invite unique id',
  link_expiration: 15,
  auth_method: 'password',
}, (err, res) => {
  // handle error or process response data
});

Deletes embedded invites for a document.

signnow.embedded.cancelInvites({
  token: 'access token',
  document_id: 'document id',
}, (err, res) => {
  // handle error or process response data
});

Promisify methods

If you are using node.js version 8.0.0 or higher you can use built in promisify utility:

const { promisify } = require('util');
const api = require('@signnow/api-client')({
  credentials: 'ENCODED_CLIENT_CREDENTIALS',
  production: false, // if false uses eval server
});
const requestToken = promisify(api.oauth2.requestToken);

requestToken({
  username: 'username',
  password: 'password',
})
  .then(res => {
    // process response data
  })
  .catch(err => {
    // handle error
  });

If you are using node.js version prior to 8.0.0 you can use our own simple promisify utility:

const { promisify } = require('@signnow/api-client/utils');
const api = require('@signnow/api-client')({
  credentials: 'ENCODED_CLIENT_CREDENTIALS',
  production: false, // if false uses eval server
});
const requestToken = promisify(api.oauth2.requestToken);

requestToken({
  username: 'username',
  password: 'password',
})
  .then(res => {
    // process response data
  })
  .catch(err => {
    // handle error
  });

Unit Tests

To run the unit test you will need to install "Mocha" and "Chai". You also need to edit a test.settings.js in the test folder of the api client module. The file need to contain the following:

exports.settings = {
  credentials: '[ENCODED CLIENT CREDENTIALS]',
  token: '[ACCESS TOKEN]',
  username: '[SIGNNOW USERNAME]',
  password: '[SIGNNOW PASSWORD]',
  documentid: '[EXISTING DOCUMENT ID]',
  templateid: '[EXISTING TEMPLATE ID]',
  folderid: '[EXISTING FOLDER ID]',
  email: '[FROM EMAIL FOR INVITE]',
  testemail: '[TO EMAIL FOR INVITE]',
};

License

This project is released under the MIT License.

Additional Contact Information

Support

To contact SignNow support, please email [email protected] or [email protected].

Sales

For pricing information, please call (800) 831-2050, email [email protected] or visit https://www.signnow.com/contact.