SignNow.NET 1.3.0

signNow.NET

About signNow

signNow.Net is the official .NET 4.5+ and .NET Standard class library for the signNow API. signNow allows you to embed legally-binding e-signatures into your app, CRM or cloud storage. Send documents for signature directly from your website. Invite multiple signers to finalize contracts. Track status of your requests and download signed copies automatically.

Get your account at https://www.signnow.com/developers

Table of Contents

1. Get started
2. Platform dependencies
3. Installation
4. Documentation
5. Features
   • Authorization
     • Request Access Token
     • Verify Access Token
     • Refresh Access Token
   • User
     • Creates an account for a user
     • Retrieve User Information
     • Sends verification email to a user
     • Change User details
     • Sends password reset link via email
     • Get modified documents
     • Get user documents
   • Document
     • Upload a document to signNow
     • Upload a document & Extract Fields
     • Download a document from signNow
     • Retrieve a document resource
     • Merge two or more signNow documents into one
     • Create a signing link to the document for signature
     • Create a freeform invite to the document for signature
     • Create a role-based invite to the document for signature
     • Create embedded signing invite to the document for signature
     • Create a one-time link to download the document as a PDF
     • Get the history of a document
     • Check the status of the document
     • Move document into specified folder
     • Edit document
     • Prefill document text fields
   • Template
     • Create a template by flattening an existing document
     • Create document from the template
   • Document Group
     • Create a document group
     • Delete document group
     • Rename document group
     • Create a copy of document group
     • Download document group
     • Move document group
     • Get document group info
     • Get all document groups the user owns
   • Folders
     • Get all folders
     • Get folder by Id
     • Create folder
     • Rename folder
     • Delete folder
6. Contribution guidelines
   • XML doc generation
   • Important notes
7. License

Get started

To start using the API 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: signNow API Reference.

API and Application

Platform Dependencies

Windows

• .Net Framework 4.5 or newer version should be installed in your system, or
• .Net Core 3.0 and newer

MacOS and Linux

• .Net Core 3.0 and newer

Installation

Install .Net package

dotnet add package SignNow.Net --version <package-version>

Install using Package manager

Install-Package SignNow.Net -Version <package-version>

Documentation

Read about the available signNow features in signNow API Docs.

Features

Authorization

Request Access Token

Get your access token via OAuth 2.0 service.

public static class AuthenticationExamples
{
    /// <summary>
    /// An example of obtaining an access token via OAuth 2.0 service.
    /// </summary>
    /// <param name="apiBase">signNow API base URL. Sandbox: "https://api-eval.signnow.com", Production: "https://api.signnow.com"</param>
    /// <param name="clientInfo"><see cref="CredentialModel"/> with Application Client ID and Client Secret</param>
    /// <param name="userCredentials"><see cref="CredentialModel"/> with User email and User password</param>
    public static async Task<Token> RequestAccessToken(Uri apiBase, CredentialModel clientInfo, CredentialModel userCredentials)
    {
        Uri apiBaseUrl = apiBase;

        string clientId = clientInfo.Login;
        string clientSecret = clientInfo.Password;

        string userLogin = userCredentials.Login;
        string userPassword = userCredentials.Password;

        var oauth = new OAuth2Service(apiBaseUrl, clientId, clientSecret);

        return await oauth.GetTokenAsync(userLogin, userPassword, Scope.All)
            .ConfigureAwait(false);
    }
}

More examples: Request Access token, Verify Access Token, Refresh Access Token

User

Creates an account for a user

By default verification email is not sent to newly created User. To send it - use IUserService.SendVerificationEmailAsync(string email)

public static partial class UserExamples
{
    /// <summary>
    /// Creates an account for a user example
    /// </summary>
    /// <param name="firstname">User firstname</param>
    /// <param name="lastname">User lastname</param>
    /// <param name="email">User email</param>
    /// <param name="password">User password</param>
    /// <param name="token">Access token</param>
    /// <returns>
    /// Response with: User identity, email
    /// </returns>
    public static async Task<UserCreateResponse> CreateSignNowUser(string firstname, string lastname, string email, string password, Token token)
    {
        var signNowContext = new SignNowContext(token);

        var userRequest = new CreateUserOptions
        {
            Email = email,
            FirstName = firstname,
            LastName = lastname,
            Password = password
        };

        return await signNowContext.Users
            .CreateUserAsync(userRequest)
            .ConfigureAwait(false);
    }
}

More examples: Create User, Retrieve User information, Sends verification email to a user, Change User details, Sends password reset link via email, Get modified documents, Get user documents

Document

Upload a document to signNow

All the features in signNow require a document_id. Once you upload a document to signNow, you get the document_id from a successful response.

public static class DocumentExamples
{
    /// <summary>
    /// Uploads a PDF document to signNow and returns SignNowDocument object.
    /// </summary>
    /// <param name="pdfFilePath">Full qualified path to your PDF file.</param>
    /// <param name="token">Access token</param>
    public static async Task<SignNowDocument> UploadDocument(string pdfFilePath, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);
        var pdfFileName = "document-example.pdf";
        
        await using var fileStream = File.OpenRead(pdfFilePath);
        
        // Upload the document
        var uploadResponse = signNowContext.Documents
            .UploadDocumentAsync(fileStream, pdfFileName).Result;

        // Gets document ID from successful response
        var documentId = uploadResponse.Id;

        return await signNowContext.Documents.GetDocumentAsync(documentId);
    }
}

More examples: Upload document, Upload document with field extract, Upload document with complex tags

Download a document from signNow

Choose the type of download for your document:

• PdfOriginal - download a document in a state it's been when uploaded to signNow, before any changes
• PdfCollapsed - download a document in PDF file format
• ZipCollapsed - download a document in ZIP archive
• PdfWithHistory - download a document with its history, a full log of changes on a separate page.

public static class DocumentExamples
{
    /// <summary>
    /// Downloads signed document.
    /// <see cref="DownloadDocumentResponse"/> contains: file name, file length, Stream content
    /// </summary>
    /// <param name="documentId">ID of signed document</param>
    /// <param name="token">Access token</param>
    public static async Task<DownloadDocumentResponse> DownloadDocument(string documentId, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);
        
        // using `documentId` from the Upload document step
        return await signNowContext.Documents
                        .DownloadDocumentAsync(documentId, DownloadType.PdfCollapsed)
                        .ConfigureAwait(false);
    }
}

More examples: Download signed document

Merge two or more signNow documents into one

Merges two or more signNow documents into one single PDF file.

Steps:

• Upload documents or Get document IDs of the documents you’d like to merge
• Merge the documents

Merged document will be saved in PDF file format.

public static partial class DocumentExamples
{
    /// <summary>
    /// Merge two documents into one final document
    /// </summary>
    /// <param name="documentName">New Document name with extension</param>
    /// <param name="documentsList">List of the documents to be merged</param>
    /// <param name="token">Access token</param>
    /// <returns>
    /// <see cref="DownloadDocumentResponse"/> contains: file name, file length, Stream content
    /// </returns>
    public static async Task<DownloadDocumentResponse>
        MergeTwoDocuments(string documentName, IEnumerable<SignNowDocument> documentsList, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        return await signNowContext.Documents
            .MergeDocumentsAsync(documentName, documentsList)
            .ConfigureAwait(false);
    }
}

More examples: Merge document

Create a signing link to the document for signature

Signing link - a single-use link to a document that requires a signature. When the document is signed (or the signer declines to sign it), the link is no longer valid. Having followed the link, signers can click anywhere on the document to sign it.

Steps:

• Upload a document or Get the ID of the document you’d like to have signed
• Send a signing link

public static partial class DocumentExamples
{
    /// <summary>
    /// Create a signing link to the document for signature.
    /// </summary>
    /// <param name="documentId">Identity of the document you’d like to have signed</param>
    /// <param name="token">Access token</param>
    /// <returns>
    /// Response with:
    /// <para> <see cref="SigningLinkResponse.Url"/>
    /// to sign the document via web browser using signNow credentials. </para>
    /// <para> <see cref="SigningLinkResponse.AnonymousUrl"/>
    /// to sign the document via web browser without signNow credentials. </para>
    /// </returns>
    public static async Task<SigningLinkResponse>
        CreateSigningLinkToTheDocument(string documentId, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // using `documentId` from the Upload document step
        return await signNowContext.Documents
            .CreateSigningLinkAsync(documentId).ConfigureAwait(false);
    }
}

More examples: Create signing link, Check signing status

Create a freeform invite to the document for signature

Freeform invite - an invitation to sign a document which doesn't contain any fillable fields.

Simply upload a document and send it for signature right away. No need for adding fields and configuring roles. Just add the signer's email address and customize the message in your email. The document will be available for signing via a button in the email. Clicking the button opens a document in signNow editor. Signers can click anywhere on a document to add their signature.

Remember: if your document contains even one fillable field, you have to create a role-based invite to get it signed.

public static partial class InviteExamples
{
    /// <summary>
    /// Create a freeform invite to the document for signature.
    /// </summary>
    /// <param name="document">signNow document you’d like to have signed</param>
    /// <param name="email">The email of the invitee.</param>
    /// <param name="token">Access token</param>
    /// <returns>
    /// <see cref="InviteResponse"/> which contains an Identity of invite request.
    /// </returns>
    public static async Task<InviteResponse>
        CreateFreeformInviteToSignTheDocument(SignNowDocument document, string email, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // Create freeform invite
        var invite = new FreeFormSignInvite(email)
        {
            Message = $"{email} invited you to sign the document {document.Name}",
            Subject = "The subject of the Email"
        };

        // Creating Invite request
        return await signNowContext.Invites.CreateInviteAsync(document.Id, invite).ConfigureAwait(false);
    }
}

More examples: Create freeform invite

Create a role-based invite to the document for signature

Role-based invite - an invitation to sign a document which contains at least one fillable field assigned to one role.

Role-based invites allow you to build e-signature workflows. The document can be signed by multiple signers: each with individual access settings, all arranged in a specific order.

Upload a document or create one from a template.

The document will be available for signing via a button in the email. You can customize email messages for every signer. Clicking the button opens a document in signNow editor. Signers can sign only the fields designated for their role.

You can add more roles either in signNow web app while editing the fields, or with ISignInvite interface from SDK while specifying parameters of the SignerOptions object.

public static partial class InviteExamples
{
    /// <summary>
    /// Create a role-based invite to the document for signature.
    /// </summary>
    /// <param name="document">signNow document with fields you’d like to have signed</param>
    /// <param name="email">The email of the invitee.</param>
    /// <param name="token">Access token</param>
    /// <returns><see cref="InviteResponse"/> without any Identity of invite request.</returns>
    public static async Task<InviteResponse>
        CreateRoleBasedInviteToSignTheDocument(SignNowDocument document, string email, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // Create role-based invite
        var invite = new RoleBasedInvite(document)
        {
            Message = $"{email} invited you to sign the document {document.Name}",
            Subject = "The subject of the Email"
        };

        // Creates options for signers
        var signer = new SignerOptions(email, invite.DocumentRoles().First())
            {
                ExpirationDays = 15,
                RemindAfterDays = 7,
            }
            .SetAuthenticationByPassword("***PASSWORD_TO_OPEN_THE_DOCUMENT***");

        // Attach signer to existing roles in the document
        invite.AddRoleBasedInvite(signer);

        // Creating Invite request
        return await signNowContext.Invites.CreateInviteAsync(document.Id, invite).ConfigureAwait(false);
    }
}

More examples: Create role-based invite

Create embedded signing invite to the document for signature

public static partial class InviteExamples
{
    /// <summary>
    /// Create an embedded signing invite to the document for signature.
    /// </summary>
    /// <param name="document">signNow document you’d like to have signed</param>
    /// <param name="email">The email of the invitee.</param>
    /// <param name="token">Access token</param>
    /// <returns>
    /// <see cref="EmbeddedInviteResponse"/> which contains an invite data.
    /// </returns>
    public static async Task<EmbeddedInviteResponse>
        CreateEmbeddedSigningInviteToSignTheDocument(SignNowDocument document, string email, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // create embedded signing invite
        var invite = new EmbeddedSigningInvite(document);
        invite.AddEmbeddedSigningInvite(
            new EmbeddedInvite
            {
                Email = email,
                RoleId = document.Roles[0].Id,
                SigningOrder = 1
            });

        return await signNowContext.Invites.CreateInviteAsync(document.Id, invite)
            .ConfigureAwait(false);
    }
}

More examples: Generate embedded signing link, Cancel embedded signing invite

Create a one-time link to download the document as a PDF

public static partial class DocumentExamples
{
    /// <summary>
    /// Create a one-time use URL for anyone to download the document as a PDF.
    /// </summary>
    /// <param name="documentId">Identity of the document</param>
    /// <param name="token">Access token</param>
    /// <returns><see cref="DownloadLinkResponse"/></returns>
    public static async Task<DownloadLinkResponse>
        CreateOneTimeLinkToDownloadTheDocument(string documentId, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        return await signNowContext.Documents
            .CreateOneTimeDownloadLinkAsync(documentId)
            .ConfigureAwait(false);
    }
}

More examples: Create a One-time Use Download URL

Get the history of a document

public static partial class DocumentExamples
{
    /// <summary>
    /// Retrieve the history of a document.
    /// </summary>
    /// <param name="documentId">Identity of the document</param>
    /// <param name="token">Access token</param>
    /// <returns><see cref="DocumentHistoryResponse"/></returns>
    public static async Task<IReadOnlyList<DocumentHistoryResponse>>
        GetTheDocumentHistory(string documentId, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        return await signNowContext.Documents
            .GetDocumentHistoryAsync(documentId)
            .ConfigureAwait(false);
    }
}

More examples: Get document history

Template

Create Template by flattening the existing Document

Set required templateName and documentId parameters to create the signNow Template.

public static class DocumentExamples
{
    /// <summary>
    /// Creates a template by flattening an existing document.
    /// </summary>
    /// <param name="documentId">Identity of the document which is the source of a template</param>
    /// <param name="templateName">The new template name</param>
    /// <param name="token">Access token</param>
    /// <returns><see cref="CreateTemplateFromDocumentResponse"/>Returns a new template ID</returns>
    public static async Task<CreateTemplateFromDocumentResponse>
        CreateTemplateFromTheDocument(string documentId, string templateName, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);
    
        return await signNowContext.Documents
            .CreateTemplateFromDocumentAsync(documentId, templateName)
            .ConfigureAwait(false);    
    }
}

More examples: Create a template by flattening an existing document, Create document from the template

Document Group

Create document group

Creates a document group from a list of document ids

All documents:

• Must be owned by the person creating the document group.
• Cannot be templates.
• Cannot already be a part of another document group (delete document group first to add them).
• At least one of the documents must have fields.

public async Task<DocumentGroupInfoResponse> CreateDocumentGroupAsync()
{
     // using token from the Authorization step
    var signNowContext = new SignNowContext(token);
    
    // Upload test documents
    await using var fileStream = File.OpenRead("./PdfWithSignatureField.pdf");

    var documents = new List<SignNowDocument>();

    for (int i = 0; i < 2; i++)
    {
        var upload = await signNowContext.Documents
            .UploadDocumentAsync(fileStream, $"ForDocumentGroupFile-{i}.pdf");
        var doc = await signNowContext.Documents.GetDocumentAsync(upload.Id).ConfigureAwait(false);
        documents.Add(doc);
    }

    // Create document group from uploaded documents
    var documentGroup = await signNowContext.DocumentGroup
        .CreateDocumentGroupAsync("CreateDocumentGroupExample", documents)
        .ConfigureAwait(false);

    // Get document group by id
    return await signNowContext.DocumentGroup
        .GetDocumentGroupInfoAsync(documentGroup.Id)
        .ConfigureAwait(false);
}

More examples: Document group operations

Folders

Get all folders

public static class FolderExamples
{
    /// <summary>
    /// Get all folders of a user.
    /// </summary>
    /// <param name="token">Access token</param>
    /// <returns>Returns all information about user's folders.</returns>
    public static async Task<SignNowFolders> GetAllFolders(Token token)
    {
        var signNowContext = new SignNowContext(token);

        return await signNowContext.Folders
            .GetAllFoldersAsync()
            .ConfigureAwait(false);
    }
}

More examples: Get all folders, Get folder, Create folder

Contribution guidelines

XML doc generation

For XML documentation generation, install InheritDocTool:

dotnet tool install -g InheritDocTool

More about the InheritDoc here

Important notes

Thanks to all contributors who got interested in this project. We're excited to hear from you. Here are some tips to make our collaboration meaningful and bring its best results to life:

• We accept pull requests from the community. Please, send your pull requests to the DEVELOP branch which is the consolidated work-in-progress branch. We don't accept requests to the Master branch.
• Please, check in with the documentation first before you open a new Issue.
• When suggesting new functionality, give as many details as possible. Add a test or code example if you can.
• When reporting a bug, please, provide full system information. If possible, add a test that helps us reproduce the bug. It will speed up the fix significantly.

License

This SDK is distributed under the MIT License, see LICENSE for more information.

API Contact Information

If you have questions about the signNow API, please visit signNow API Reference or email api@signnow.com.

Support: To contact signNow support, please email support@signnow.com or api@signnow.com.

Sales: For pricing information, please call (800) 831-2050, email sales@signnow.com or visit https://www.signnow.com/contact.