Send Signature Requests Using DigiSigner API

This tutorial explains how to send signature requests for your documents using our eSignature API (Application Programming Interface).

Send Out Documents for Signing

The most simple case is when you need to send out a document for signing without specifying any fields. In this case the signer or the signers will be able to sign your document where they feel it should be done.

Please note that if you want to send a signature request from your command line using CURL, you would need to upload your document to DigiSigner first. We will show how to do it in our first code sample, but later we will skip this step each time. The upload request will return the document_id parameter of the uploaded document, which you will use as an input parameter in the signature request.

This doesn't apply if you are using our PHP or Java client libraries. Then you will only need to perform one API call, which will automatically upload your document and send the signature request for you.

In the following code sample we demonstrate how to send such a signature request.

# upload document.pdf            
curl -u YOUR_API_KEY: -F file=@document.pdf https://api.digisigner.com/v1/documents

# got response: {"document_id":"5be88823-3ff5-4ec4-8175-459dee50f7fb"}

# send signature request            
curl -u YOUR_API_KEY: https://api.digisigner.com/v1/signature_requests \
-H 'Content-Type: application/json' \
-d '{"documents" : [ \
      {"document_id": "5be88823-3ff5-4ec4-8175-459dee50f7fb", \
       "signers": [{"email": "invited_signer@email.com"}] \
      }] \
    }'    
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$request = new SignatureRequest;
  
$document = new Document('document.pdf');
$request->addDocument($document);

$signer = new Signer('invited_signer@email.com');
$document->addSigner($signer);

$response = $client->sendSignatureRequest($request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();
 
Document document = new Document(new File("document.pdf")); 
request.addDocument(document);

Signer signer = new Signer("invited_signer@email.com");
document.addSigner(signer);

SignatureRequest response = client.sendSignatureRequest(request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();
 
Document document = new Document("document.pdf"); 

Signer signer = new Signer("invited_signer@email.com");
document.Signers.Add(signer);

request.Documents.Add(document);
SignatureRequest response = client.SendSignatureRequest(request);
            

This was the most simple signature request that is possible. It will work, but in most cases it makes sense to specify explicitely where people should sign your document or add text to it. That makes the signing process easier for them and reduces the potential for errors. This can be done by using fields.

Send Out Documents With Fields

The following code sample demonstrates how to send out a document with specified fields.

The signers will be able to insert their signatures and enter texts only in these fields. They will be also guided from field to field, which makes the signing process easier and less error-prone.

curl -u YOUR_API_KEY: https://api.digisigner.com/v1/signature_requests \
-H 'Content-Type: application/json' \
-d '{"documents" : [ \
      {"document_id": "{document_id}", \
       "signers": [ \
        {"email": "invited_signer@email.com", \
         "fields": [ \
          {"page": 0, \
           "rectangle": [100, 200, 200, 250], \ 
           "type": "SIGNATURE" \    
          }, \         
          {"page": 0, \
           "rectangle": [300, 200, 400, 220], \ 
           "type": "TEXT" \    
          }] \
        }] \
      }] \
    }'    
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$request = new SignatureRequest;
  
$document = new Document('document.pdf');
$request->addDocument($document);

$signer = new Signer('invited_signer@email.com');
$document->addSigner($signer);

$field1 = new Field(0, array(100, 200, 200, 250), Field::TYPE_SIGNATURE);
$signer->addField($field1);

$field2 = new Field(0, array(300, 200, 400, 220), Field::TYPE_TEXT);
$signer->addField($field2);

$response = $client->sendSignatureRequest($request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();
 
Document document = new Document(new File("document.pdf")); 
request.addDocument(document);

Signer signer = new Signer("invited_signer@email.com");
document.addSigner(signer);

Field field1 = new Field(0, new int[] {100, 200, 200, 250}, FieldType.SIGNATURE);
signer.addField(field1);

Field field2 = new Field(0, new int[] {300, 200, 400, 220}, FieldType.TEXT);
signer.addField(field2);

SignatureRequest response = client.sendSignatureRequest(request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();

Document document = new Document("document.pdf");
Signer signer = new Signer("invited_signer@email.com");

Field field1 = new Field(0, new int[] { 100, 200, 200, 250 }, FieldType.SIGNATURE);
signer.Fields.Add(field1);

Field field2 = new Field(0, new int[] { 300, 200, 400, 220 }, FieldType.TEXT);
signer.Fields.Add(field2);

document.Signers.Add(signer);
request.Documents.Add(document);
SignatureRequest response = client.SendSignatureRequest(request);
            

In the above sample code we send out a document for signing and specify one signature field, where the document should be signed, and one text field, where some text should be entered.

Both fields are specified using their coordinates in the format [x1, y1, x2, y2]. We use the standard PDF coordinate system here, the origin of the document is at the bottom-left corner.

We support the following types of fields: SIGNATURE, TEXT, INITIALS, DATE, CHECKBOX. For each field you can specify also other parameters, like label or content. For the full list of parameters please see Signature Request Parameters.

Send Out Documents to Multiple Signers

You can send out one and the same document for signing to multiple signers. Here is the sample code for sending out one document to two signers.

curl -u YOUR_API_KEY: https://api.digisigner.com/v1/signature_requests \
-H 'Content-Type: application/json' \
-d '{"documents" : [ \
      {"document_id": "{document_id}", \
       "signers": [ \
        {"email": "invited_signer_1@email.com"}, \
        {"email": "invited_signer_2@email.com"} \
       ] \
      }] \
    }'    
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$request = new SignatureRequest;
  
$document = new Document('document.pdf');
$request->addDocument($document);

$signer1 = new Signer('invited_signer_1@email.com');
$document->addSigner($signer1);

$signer2 = new Signer('invited_signer_2@email.com');
$document->addSigner($signer2);

$response = $client->sendSignatureRequest($request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();
 
Document document = new Document(new File("document.pdf")); 
request.addDocument(document);

Signer signer1 = new Signer("invited_signer_1@email.com");
document.addSigner(signer1);

Signer signer2 = new Signer("invited_signer_2@email.com");
document.addSigner(signer2);

SignatureRequest response = client.sendSignatureRequest(request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();

Document document = new Document("document.pdf");

Signer signer1 = new Signer("invited_signer_1@email.com");
document.Signers.Add(signer1);

Signer signer2 = new Signer("invited_signer_2@email.com");
document.Signers.Add(signer2);

request.Documents.Add(document);
SignatureRequest response = client.SendSignatureRequest(request);
            

For simplicity we haven't specified fields for the signers, but of course you can do it.

Both signers will receive the emails with the link to the document at the same time and can sign it independent from each other.

How to Set Up Signing Order

Sometimes when you have multiple signers you don't want to send your document to all signers at once. Let's assume that you want to send your document to the first signer, and only when they complete it, the document should be automatically sent to the second signer.

This is how you can do it.

curl -u YOUR_API_KEY: https://api.digisigner.com/v1/signature_requests \
-H 'Content-Type: application/json' \
-d '{"documents" : [ \
      {"document_id": "{document_id}", \
       "signers": [ \
        {"email": "invited_signer_1@email.com", \
         "order": 1 \
        }, \
        {"email": "invited_signer_2@email.com", \
         "order": 2 \
        }] \
      }] \
    }'    
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$request = new SignatureRequest;
  
$document = new Document('document.pdf');
$request->addDocument($document);

$signer1 = new Signer('invited_signer_1@email.com');
$signer1->setOrder(1);
$document->addSigner($signer1);

$signer2 = new Signer('invited_signer_2@email.com');
$signer2->setOrder(2);
$document->addSigner($signer2);

$response = $client->sendSignatureRequest($request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();
 
Document document = new Document(new File("document.pdf")); 
request.addDocument(document);

Signer signer1 = new Signer("invited_signer_1@email.com");
signer1.setOrder(1);
document.addSigner(signer1);

Signer signer2 = new Signer("invited_signer_2@email.com");
signer2.setOrder(2);
document.addSigner(signer2);

SignatureRequest response = client.sendSignatureRequest(request);
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest request = new SignatureRequest();

Document document = new Document("document.pdf");
            
Signer signer1 = new Signer("invited_signer_1@email.com");
signer1.Order = 1;
document.Signers.Add(signer1);

Signer signer2 = new Signer("invited_signer_2@email.com");
signer2.Order = 2;
document.Signers.Add(signer2);

request.Documents.Add(document);
SignatureRequest response = client.SendSignatureRequest(request);
            

For each signer we specified the order in the signing queue. The signer1 will receive the link to the document as the first, and only after completion the document will be sent to the signer2.

You can use the signing order feature to build much more sophisticated workflows. For example if you have 5 signers, and two of them need to sign the document as first (doesn't matter in which order), then the document should be sent to the third signer, and only after that to the last two (the order between them is also not essential).

Here is how you can construct your workflow by assigning each signer a corresponding order.

SignerOrderComment
signer 11receives document immediately
signer 21receives document immediately
signer 32receives document only after both signers 1 and 2 have signed
signer 43receives document immediately after signer 3 has signed
signer 53receives document immediately after signer 3 has signed

More tutorials and documentation

Signature Request Parameters - all signature request parameters

How to Embed Documents - how to embed documents on your web site to get them filled out and signed

How to Use Templates Via API - how to configure your templates in GUI mode and use them via our API

How to Use Text Tags In Your Documents - how to specify fields in your documents using pieces of text

How to Get Data Submitted By Signers - how to retrieve data signers entered while filling out your form


Don't hesitate to contact us in case you have any questions or suggestions about using our API.