Skip to content

Latest commit

 

History

History
404 lines (299 loc) · 12.8 KB

README.md

File metadata and controls

404 lines (299 loc) · 12.8 KB
Raw

HelloSign .NET SDK

Build status

An official library for using the HelloSign API written in C#.NET and powered by RestSharp.

This SDK is currently in beta. If you need help:

  • Use the Issue Tracker to report bugs or missing functionality in this library.
  • Send an email to [email protected] to request help with our API or your account.

Installation

The HelloSign .NET SDK can be installed using the NuGet package manager, under the package name HelloSign (package details).

If you prefer not to use NuGet, you can download a ZIP archive containing the built .dll files from the Releases page, or clone this repository and build the project yourself (see "Build from Source" below).

Usage

First, use our namespace:

using HelloSign;

Create a client object:

var client = new Client("ACCOUNT API KEY HERE"); // Preferred
// Or...
var client = new Client("EMAIL ADDRESS HERE", "PASSWORD HERE"); // Not preferred

Error Handling

Most methods will throw a relevant exception if something goes wrong. This includes when our server returns an error message documented here.

You should always be prepared to catch these exceptions and handle them appropriately. Refer to HelloSign/Exceptions.cs in this repository for information about the custom exception classes this library defines.

Warnings

Some API responses include one or more warnings if there was a non-fatal problem with your request. At any time, you may inspect the contents of client.Warnings (a List of HelloSign.Warning objects) and output them as you see fit.

Callback Event Parsing

If you're implementing a server that will receive callbacks from HelloSign, this library can parse the received JSON into a native object and perform the hash-based integrity check for you.

String eventJson = ...; // Get this string from the 'json' POST parameter in the HTTP request
Event myEvent = client.ParseEvent(eventJson);

// The Event object contains accessors for all related data.
Console.WriteLine("Received event with type: " + event.EventType);
SignatureRequest request = myEvent.SignatureRequest;

Account Methods

Get your Account details

var account = client.GetAccount();
Console.WriteLine("My Account ID is: " + account.AccountId);

Update your Account Callback URL

var account = client.UpdateAccount("https://example.com/hellosign.asp");
Console.WriteLine("Now my Callback URL is: " + account.CallbackUrl);

Create a new Account

// Throws exception if account already exists
var account = client.CreateAccount("[email protected]");
Console.WriteLine("The new Account's ID is: " + account.AccountId);

Signature Request Methods

Send Signature Request using files (non-Embedded)

var request = new SignatureRequest();
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("[email protected]", "Jack");
request.AddSigner("[email protected]", "Jill");
request.AddCc("[email protected]");
request.AddFile("c:\users\me\My Documents\nda.txt");
request.AddFile("c:\users\me\My Documents\AppendixA.txt");
request.Metadata.Add("custom_id", "1234");
request.Metadata.Add("custom_text", "NDA #9");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
Console.WriteLine("New Signature Request ID: " + response.SignatureRequestId);

Note: You can optionally pass an API App client ID as a second parameter to SendSignatureRequest.

Send Signature Request using files and form fields (non-Embedded)

var request = new SignatureRequest();
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("[email protected]", "Jack");
request.AddFile("c:\users\me\My Documents\nda.pdf").WithFields(
    //            id      type                     page    x    y    w   h   req signer
    new FormField("chk1", FormField.TypeCheckbox,     1, 140,  72,  36, 36, true,     0),
    new FormField("txt1", FormField.TypeText,         1, 140, 144, 225, 20, true,     0),
    new FormField("dat1", FormField.TypeDateSigned,   1, 140, 216, 225, 52, true,     0),
    new FormField("sig1", FormField.TypeSignature,    1, 140, 288, 225, 52, true,     0),
);
request.TestMode = true;
var response = client.SendSignatureRequest(request);
Console.WriteLine("New Signature Request ID: " + response.SignatureRequestId);

Send Signature Request using a template (non-Embedded)

var request = new TemplateSignatureRequest();
request.AddTemplate("TEMPLATE ID HERE");
request.Subject = "Purchase Order";
request.Message = "Glad we could come to an agreement.";
request.AddSigner("Client", "[email protected]", "George");
request.AddCc("Accounting", "[email protected]");
request.CustomFields.Add("Cost", "$20,000");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
Console.WriteLine("New Template Signature Request ID: " + response.SignatureRequestId);

Note: You can optionally pass an API App client ID as a second parameter to SendSignatureRequest.

Create Embedded Signature Request using files

var request = new SignatureRequest();
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("[email protected]", "Jack");
request.AddSigner("[email protected]", "Jill");
request.AddCc("[email protected]");
request.AddFile("c:\users\me\My Documents\nda.txt");
request.AddFile("c:\users\me\My Documents\AppendixA.txt");
request.Metadata.Add("custom_id", "1234");
request.Metadata.Add("custom_text", "NDA #9");
request.TestMode = true;
var response = client.CreateEmbeddedSignatureRequest(request, "CLIENT ID HERE");
Console.WriteLine("New Embedded Signature Request ID: " + response.SignatureRequestId);

Create Embedded Signature Request using a template

var request = new TemplateSignatureRequest();
request.AddTemplate("TEMPLATE ID HERE");
request.Subject = "Purchase Order";
request.Message = "Glad we could come to an agreement.";
request.AddSigner("Client", "[email protected]", "George");
request.AddCc("Accounting", "[email protected]");
request.AddCustomField("Cost", "$20,000");
request.TestMode = true;
var response = client.CreateEmbeddedSignatureRequest(request, "CLIENT ID HERE");
Console.WriteLine("New Template-based Embedded Signature Request ID: " + response.SignatureRequestId);

Get info about an existing Signature Request

var request = client.GetSignatureRequest("SIGNATURE REQUEST ID HERE");
Console.WriteLine("Signature Request title: " + request.Title);

Cancel a Signature Request

client.CancelSignatureRequest("SIGNATURE REQUEST ID HERE");

Remind a Signer to Sign

client.RemindSignatureRequest("SIGNATURE REQUEST ID HERE", "EMAIL ADDRESS HERE");

Update a Signature Request

client.UpdateSignatureRequest("SIGNATURE REQUEST ID HERE", "SIGNATURE ID HERE", "NEW EMAIL ADDRESS HERE");

Download a Signature Request (in its current state) and save to disk

// Download a merged PDF
client.DownloadSignatureRequestFiles("SIGNATURE REQUEST ID HERE", "/path/to/output.pdf");
// Or download a ZIP containing individual unmerged PDFs
client.DownloadSignatureRequestFiles("SIGNATURE REQUEST ID HERE", "/path/to/output.pdf", SignatureRequest.FileType.ZIP);

Download a Signature Request (in its current state) as bytes

// Download a merged PDF
var bytes = client.DownloadSignatureRequestFiles("SIGNATURE REQUEST ID HERE");
// Or download a ZIP containing individual unmerged PDFs
var bytes = client.DownloadSignatureRequestFiles("SIGNATURE REQUEST ID HERE", SignatureRequest.FileType.ZIP);

Get a temporary URL to download a Signature Request

var url = client.GetSignatureRequestDownloadUrl("SIGNATURE REQUEST ID HERE");
Console.WriteLine("The download URL is: " + url.FileUrl);
Console.WriteLine("The URL expires at: " + url.ExpiresAt);

Embedded Methods

Retrieve Embedded Signing URL for a particular signer

var response = client.GetSignUrl("SIGNATURE ID HERE");
Console.WriteLine("Signature URL for HelloSign.open(): " + response.SignUrl);

Retrieve Embedded Templates Editing URL

var response = client.GetEditUrl("EMBEDDED TEMPLATE ID HERE");
Console.WriteLine("Editing URL for HelloSign.open(): " + response.EditUrl);

Unclaimed Draft Methods (for Embedded Requesting)

Not implemented

Template Methods

Get Template details

var template = client.GetTemplate("TEMPLATE ID HERE");

Add an Account to a Template

var template = client.AddAccountToTemplate("TEMPLATE ID HERE", "ACCOUNT ID HERE");
// Or...
var template = client.AddAccountToTemplate("TEMPLATE ID HERE", null, "EMAIL ADDRESS HERE");

Remove an Account from a Template

var template = client.RemoveAccountFromTemplate("TEMPLATE ID HERE", "ACCOUNT ID HERE");
// Or...
var template = client.RemoveAccountFromTemplate("TEMPLATE ID HERE", null, "EMAIL ADDRESS HERE");

Download a Template as a PDF and save to disk

client.DownloadTemplateFiles("TEMPLATE ID HERE", "/path/to/output.pdf");

Download a Template as a PDF, as bytes

var bytes = client.DownloadTemplateFiles("TEMPLATE ID HERE");

Get a temporary URL to download a Template's files

var url = client.GetTemplateFilesDownloadUrl("TEMPLATE ID HERE");
Console.WriteLine("The download URL is: " + url.FileUrl);
Console.WriteLine("The URL expires at: " + url.ExpiresAt);

Delete a Template

client.DeleteTemplate("TEMPLATE ID HERE");

Create a new Embedded Template Draft

var draft = new EmbeddedTemplateDraft();
draft.TestMode = true;
draft.AddFile(file1, "NDA.txt");
draft.Title = "Test Template";
draft.Subject = "Please sign this document";
draft.Message = "For your approval.";
draft.AddSignerRole("Client", 0);
draft.AddSignerRole("Witness", 1);
draft.AddCcRole("Manager");
draft.AddMergeField("Full Name", MergeField.FieldType.Text);
draft.AddMergeField("Is Registered?", MergeField.FieldType.Checkbox);
var response = client.CreateEmbeddedTemplateDraft(draft, "CLIENT ID HERE");

Team Methods

Get your Team details

var team = client.GetTeam();

Create a new Team

var team = client.CreateTeam("NAME HERE");

Update your Team name

var team = client.UpdateTeamName("NAME HERE");

Delete your Team

var team = client.DeleteTeam();

Add a member to your Team

var team = AddMemberToTeam("ACCOUNT ID HERE");
// Or...
var team = AddMemberToTeam(null, "EMAIL ADDRESS HERE");

Remove a member from your Team

var team = RemoveMemberFromTeam("ACCOUNT ID HERE");
// Or...
var team = RemoveMemberFromTeam(null, "EMAIL ADDRESS HERE");

Build from Source

Windows

Use Visual Studio (Express).

Linux (and OSX?) using Mono

  1. Install Mono
  2. Install NuGet
  3. mkdir packages
  4. cd HelloSign
  5. nuget install -o ../packages
  6. cd ..
  7. xbuild (or xbuild /p:Configuration=Release for a non-Debug build)

Packaging for NuGet

  1. cd HelloSign
  2. nuget pack HelloSign.csproj -Prop Configuration=Release

License

The MIT License (MIT)

Copyright (C) 2015 hellosign.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.