Sending a casefile

Let's send a CaseFile with Penneo!

First, we get our caseFile, document, and signer ready...

1. Create a casefile

API

// Create a new case file

POST <<penneo_api_base_url>>/casefiles
{
  "title":"Demo case file"
}

C#

// Create a new case file

var myCaseFile = new CaseFile("Demo case file");
myCaseFile.Persist(connector);

PHP

// Create a new case file

$myCaseFile = new CaseFile();
$myCaseFile->setTitle('Demo case file');
CaseFile::persist($myCaseFile);

1.a. Link to a folder

You'll probably want to put your casefile in a folder, so you can find it again later.

API

POST <<penneo_api_base_url>>/folders/<folder id>/casefiles/<your casefile id>

C#

// Retrieve a specific folder (by id)

var myFolder = Query.Find<Folder>(<your folder id>);
myFolder.AddCaseFile(myCaseFile);
myCaseFile.Persist(connector);

PHP

// Retrieve a specific folder (by id)

$myFolder = Folder::find(<your folder id>);
$myFolder->addCaseFile($myCaseFile);
CaseFile::persist($myCaseFile);

2. Add a document to your casefile

API

// Create a new signable document in this case file

POST <<penneo_api_base_url>>/documents
{
  "caseFileId": <your casefile id>
  "title":"Demo document",
  "pdfFile":"<base 64 encoded PDF document",
  "type":"signable"
}

C#

// Create a new signable document in this case file

var myDocument = new Document(myCasefile, "Demo Document", "/path/to/pdfFile");
myDocument.MakeSignable();
myDocument.Persist(connector);

PHP

// Create a new signable document in this case file

$myDocument = new Document($myCaseFile);
$myDocument->setTitle('Demo document');
$myDocument->setPdfFile('/path/to/pdfFile');
$myDocument->makeSignable();
Document::persist($myDocument);

3. Add a signer

API

// Create a new signer that can sign documents in the case file

POST <<penneo_api_base_url>>/casefiles/<your casefile id>/signers
{
  "name":"John Doe"
}

C#

// Create a new signer that can sign documents in the case file

var mySigner = new Signer(myCaseFile, "John Doe");
mySigner.Persist(connector);

PHP

// Create a new signer that can sign documents in the case file

$mySigner = new Signer($myCaseFile);
$mySigner->setName('John Doe');
Signer::persist($mySigner);

4. Create a signature line

Now, we can connect the signer to the document.

API

// Create a new signature line on the document

POST <<penneo_api_base_url>>/documents/<your document id>/signaturelines
{
  "role":"MySignerRole",
  "signOrder": 0
}

C#

// Create a new signature line on the document

var mySignatureLine = new SignatureLine(myDocument, "MySignerRole");
mySignatureLine.Persist(connector);

PHP

// Create a new signature line on the document

$mySignatureLine = new SignatureLine($myDocument);
$mySignatureLine->setRole('MySignerRole');
SignatureLine::persist($mySignatureLine);

Note: Your document ID comes from the JSON response you get when you create a document in step 2.
The JSON will contain a numerical id and a user-friendly alphanumeric documentId.
For creating a signature line you will need the numerical id.

5. Link the signer to the signature line

API

// Link the signer to the signature line

POST <<penneo_api_base_url>>/documents/<your document id>/signaturelines/<your signature line id>/signers/<your signer id>

C#

// Map the signer to the signing request

mySignatureLine.SetSigner(connector, mySigner);

PHP

// Link the signer to the signature line
$mySignatureLine->setSigner($mySigner);

6. Distribute the signing request links

The signing requests links can be distributed in 2 ways:

• distribute the signing links yourself
• let Penneo administer the distribution of the signing links

6.a. Distribute the signing request link yourself

If you are distributing the links yourself, then you can extract them as follows:

API

// And finally, print out the link leading to the signing page.
// The signer uses this link to sign the document.

PATCH <<penneo_api_base_url>>/signingrequests/<your signing request id>/link

C#

// And finally, print out the link leading to the signing portal.
// The signer uses this link to sign the document.

Console.WriteLine("<a href=\"" + mySigningRequest.GetLink() + "\">Sign now</a>");

PHP

// And finally, print out the link leading to the signing portal.
// The signer uses this link to sign the document.

print('<a href="'.$mySigningRequest->getLink().'">Sign now</a>');

6.b. [Optional] Use Penneo for distributing the signing request links

If you want Penneo to send the link for you? Let's see what we need to do to make that happen.

Since we're letting Penneo handle the emails, we need to add a lot more info to our signing request. We can configure parameters such as subject, content and format for all emails. Reminder intervals can be configured for reminder emails.

API

// Update the signing request for the new signer

GET <<penneo_api_base_url>>/casefiles/<your casefile id>/signers/<your signer id>/signingrequests

// This gives you the ID of your signing request. Remember, it gets created automatically when you link a signer to a signature line.

PUT <<penneo_api_base_url>>/signingrequests/<your signing reqest id>
{
  // John's email
  "email":"[email protected]",
  
  // The subject and text of the first email he gets.
  "emailSubject":"An offer you can't refuse",
  "emailText":"Hi {{recipient.name}}! Your contract is ready for you.",
  
  // Let's send him a reminder every 4 days.
  "reminderInterval":4,
  "reminderEmailSubject":"You forgot to sign your contract, {{recipient.name}}.",
  "reminderEmailText":"Dear {{recipient.name}}. You haven't signed your contract yet. We'll try not to take it personally.",
  
  // Let him sign with touch.
  "enableInsecureSigning":true
}

C#

// Update the signing request for the new signer
var mySigningRequest = mySigner.GetSigningRequest(connector);

// John's email
mySigningRequest.Email = "[email protected]";
  
// The subject and text of the first email he gets.
mySigningRequest.EmailSubject = "An offer you can't refuse";
mySigningRequest.EmailText = "Hi {{recipient.name}}! Your contract is ready for you.";

//The subject and text for the completed email
mySigningRequest.CompletedEmailSubject = "Documents have been signed";
mySigningRequest.CompletedEmailText = "Hi {{recipient.name}}! The contract has been signed by all parties.";
  
// Let's send him a reminder every 4 days, with a custom message.
mySigningRequest.ReminderInterval = 4;
mySigningRequest.ReminderEmailSubject = "You forgot to sign your contract, {{recipient.name}}.";
mySigningRequest.ReminderEmailText = "Dear {{recipient.name}}. You haven't signed your contract yet. We'll try not to take it personally.";

//Verify Social Security Number/Vatin before documents are about to be signed
mySigningRequest.AccessControl = true;
  
// Let him sign with touch. Because we're nice like that.
mySigningRequest.EnableInsecureSigning = true;

//Persist using the Penneo Connector
mySigningRequest.Persist(connector);

PHP

// Update the signing request for the new signer
$mySigningRequest = $mySigner->getSigningRequest();

// John's email
$mySigningRequest->setEmail('[email protected]');
  
// The subject and text of the first email he gets.
$mySigningRequest->setEmailSubject('An offer you can\'t refuse');
$mySigningRequest->setEmailText('Hi {{recipient.name}}! Your contract is ready for you.');
  
// Let's send him a reminder every 4 days, with a custom message.
$mySigningRequest->setReminderInterval(4);
$mySigningRequest->setReminderEmailSubject('You forgot to sign your contract, {{recipient.name}}');
$mySigningRequest->setReminderEmailText('Dear {{recipient.name}}. You haven\'t signed your contract yet. We\'ll try not to take it personally.');
  
// Let him sign with touch. Because we're nice like that.
$mySigningRequest->setEnableInsecureSigning(true);

SigningRequest::persist($mySigningRequest);

📘

HTML content in emails

You can opt to send HTML formatted emails. By default, the email format is set to text. For a specific example of how to send html formatted emails, explore this example: https://github.com/Penneo/api-utils/blob/master/cs/2.x/casefile/one-doc-one-signer/run.cs

This feature is disabled by default. If you want to enable it, contact Penneo support at [email protected].

📘

Dynamic content in the emails

You can add dynamic content in your emails using merge fields such as case file title, sender name, recipient name, signing request link etc. For details, have a look at the api documentation: https://sandbox.penneo.com/api/docs/#/Signing%20requests/put_api**version**signingrequests__requestId_

You can see a few examples: https://github.com/penneo/api-utils#email-templates

7. Activate the casefile

This step activates the casefile. If the signing request contains email details then emails will be also sent.

API

// Activate the casefile and send all the signing emails.

PATCH <<penneo_api_base_url>>/casefiles/<your casefile id>/send

C#

// Send all the signing emails.

myCaseFile.Send();

PHP

// Send all the signing emails.

$myCaseFile->send();

You can see a few examples: https://github.com/penneo/api-utils#email-templates

Boom. You're done.