Get Data Submitted By Signers Using DigiSigner API

This tutorial explains how to retrieve data that people entered by filling out and signing your forms using our eSignature API.

Identify Fields

You can only retrieve data entered by signers in some fields. You also need a way identify the fields you add to your form, otherwise you won't be able determine what data was entered in which particular field.

We offer a way to specify identifiers for your fields while sending out a signature request, and later retrieve all the data that signers have entered in these fields. This data will come with the field identifiers that you specified, so you will know what data has been entered in which field.

To identify your fields, for each of them you would need to specify the api_id parameter. The value for this parameter can be any non-empty string.

It makes sense to select unique api_ids for your fields within each signature request (though it is not a requirement), otherwise you won't be able to differentiate between different fields later.

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, 220], \ 
           "type": "TEXT", \
           "api_id": "name" \   
          }, \         
          {"page": 0, \
           "rectangle": [300, 200, 400, 220], \ 
           "type": "TEXT", \
           "api_id": "title" \    
          }] \
        }] \
      }] \
    }'    
            
$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_TEXT);
$field1->setApiId("name");
$signer->addField($field1);

$field2 = new Field(0, array(300, 200, 400, 220), Field::TYPE_TEXT);
$field2->setApiId("title");
$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.TEXT);
field1.setApiId("name");
signer.addField(field1);

Field field2 = new Field(0, new int[] {300, 200, 400, 220}, FieldType.TEXT);
field2.setApiId("title");
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");
document.Signers.Add(signer);

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

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

request.Documents.Add(document);

SignatureRequest response = client.SendSignatureRequest(request);
            

In the code above we have two text fields, one for the signer's name, the other for the title. We selected title as api_id for the title field, and name for the name field.

You can use any scheme to generate your api_ids, like e.g. Universally Unique Identifiers.

Get Submitted Data

After the document will be filled out and submitted by the signer, your system will be notified about this event via a callback. Here you can find more info about it Signature Request Completed Callback.

In your callback handler you will need to make the following request to retrieve the entered data.

# request            
curl -u YOUR_API_KEY: https://api.digisigner.com/v1/documents/{document_id}/fields

# response
{"document_fields":[  
  {"api_id":"name",
   "submitted_content":"James Williams",
   ...
  }, 
  {"api_id":"title",
   "submitted_content":"Customer Care",
   ...
  }]
}     
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$documentFields = $client->getDocumentFields('{document_id}');

foreach($documentFields->getDocumentFields() as $field) {    
    // field api_id
    print("Api id: ".$field->getApiId()."\n");
    
    // value entered by signer
    print("Submitted value: ".$field->getSubmittedContent."\n");
}
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.getDocumentFields("{document_id}");
      
for (DocumentField field : documentFields.getDocumentFields()) {
    // field api_id
    System.out.println("Api id: " + field.getApiId());
    
    // value entered by signer
    System.out.println("Submitted content: " + field.getSubmittedContent());
}
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.GetDocumentFields("{document_id}");
      
foreach (DocumentField field in documentFields.Fileds)
{
    // field api_id
    Console.WriteLine("Api id: " + field.ApiId);

    // value entered by signer
    Console.WriteLine("Submitted content: " + field.SubmittedContent);
}
            

The response will contain more information about your document fields but in your case you will need only two attributes: api_id to identify the field and submitted_content, which is the value entered in this field by the signer.

The document_id parameter that you need for the request can be extracted from the content that DigiSigner will send you via the callback.

Get Document Attachments

If you are using fields for accepting attachments in your forms you may need to automatically download the attachments uploaded by the signer.

To do this you would need to iterate over the document fields (see the previous section), identify the filled in attachment fields (status FILLED and type ATTACHMENT) and for each of them call the API request to download the corresponding attachment (see Download Document Attachment).

See below the sample code how to do this.

# get document fields request            
curl -u YOUR_API_KEY: https://api.digisigner.com/v1/documents/{document_id}/fields

# field data response
{"document_fields":[  
  {"api_id":"06e28f74-1464-4890-9825-4ec0df1357c5",
   "status":"FILLED", 
   "type":"ATTACHMENT",
   "submitted_content":"attachment_1.pdf",   
   ...
  }, 
  {"api_id":"f9bf5865-de7e-4fd5-8be6-aa8d8f46735c",
   "status":"FILLED", 
   "type":"ATTACHMENT",
   "submitted_content":"attachment_2.pdf",
   ...
  }]
}

# get document attachment request (for each ATTACHMENT field with status FILLED)            
curl -u YOUR_API_KEY: -o attachment.pdf https://api.digisigner.com/v1/documents/{document_id}/fields/{field_api_id}/attachment   
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$documentFields = $client->getDocumentFields('{document_id}');

foreach($documentFields->getDocumentFields() as $field) {
    if ($field->getStatus() == DocumentField::STATUS_FILLED 
        && $field->getType() == Field::TYPE_ATTACHMENT) {
        $client->getDocumentAttachment('{document_id}', $field->getApiId(), 'attachment.pdf');
    }    
}
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.getDocumentFields("{document_id}");
      
for (DocumentField field : documentFields.getDocumentFields()) {
    if (field.getStatus() == DocumentFieldStatus.FILLED && field.getType() == FieldType.ATTACHMENT) {
        File file = client.getDocumentAttachment("{document_id}", field.getApiId(), "attachment.pdf");    
    }
}
            
DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.GetDocumentFields("{document_id}");
      
foreach (DocumentField field in documentFields.Fileds)
{
    if (field.Status == DocumentFieldStatus.FILLED && field.Type == FieldType.ATTACHMENT)
    {
        client.GetDocumentAttachment("{document_id}", field.ApiId, "attachment.pdf");
    }
}
            

More tutorials and documentation

Signature Request Parameters - all signature request parameters

How to Send Signature Requests - code samples for sending signature requests

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


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