DigiSigner eSignature API Documentation

Introduction to eSignature API

We provide an electronic signature API built on pragmatic RESTful design principles using simple and modern technologies. Our eSignature API uses resource-oriented URLs that leverage the built-in features of HTTP. The request and response bodies are JSON encoded. Any standard HTTP client can be used to communicate with our electronic signature API.

Authentication

Our eSignature API is authenticated using HTTP Basic Auth over HTTPS. A user’s API key should be provided as auth credentials:

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

Every DigiSigner account holder is issued a personal API key and can therefore start working with our eSignature API immediately.

Your personal API key can be found in the settings section of your DigiSigner account.

2_settings_dialog

In the following examples, replace the text YOUR_API_KEY with your API key.

Please note that the initial eSignature API mode is TEST. In the TEST mode, a watermark is automatically added to all uploaded documents. You will be automatically switched to the PROD mode as soon as you upgrade your account and purchase API credits.

Upload Document

Before you can proceed with collecting signatures, you must first upload a document to DigiSigner.

If you are using our PHP, Java, or C# client libraries, you can skip this step and begin sending a signature request immediately. Our client libraries will automatically upload a document for you in the background.

URL

POST https://api.digisigner.com/v1/documents

Request

Sample request:

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

$client = new DigiSignerClient('YOUR_API_KEY'); 
$document = $client->uploadDocument('document.pdf');

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
Document document = new Document(new File("document.pdf"));
document = client.uploadDocument(document);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
string documentId = client.UploadDocument("document.pdf");

Response

Sample response:

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

The upload request returns the document_id of the uploaded document which you should use to send a signature request for this document or download it.

Download Document

Downloads the content of the document. Requires the document_id as a parameter.

URL

GET https://api.digisigner.com/v1/documents/{document_id}

Request

curl -u YOUR_API_KEY: -o document.pdf https://api.digisigner.com/v1/documents/{document_id}

$client = new DigiSignerClient('YOUR_API_KEY'); 
$client->getDocument($documentId, 'document.pdf');

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
Document retrievedDocument = client.getDocumentById(documentId, "document.pdf");

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY"); 
client.GetDocumentById(documentId, "document.pdf");

In the request, use the document_id that is returned by the ‘Upload Document’ request. The content of the file will be saved as document.pdf.

Response

The response then represents the content of the requested document.

Send Signature Request

Initiates the signature process by requesting a signature for one or more documents. In the request, you can specify the email addresses of the signers for each specific document. For every signer you can specify fields for filling in.

After sending the request every invited signer will receive an email with a link to the document to be signed. After clicking on the link, the signers will be redirected to the signature page, where they will be able to fill out and sign the document.

URL

POST https://api.digisigner.com/v1/signature_requests

Request

A sample request (one signer is invited to sign one document; the signature must be placed in the specified field):

curl -u YOUR_API_KEY: https://api.digisigner.com/v1/signature_requests \
-H 'Content-Type: application/json' \
-d '{"documents" : [ \
      {"document_id": "{document_id}", \
       "subject": "My email subject", \
       "message": "My email message", \      
       "signers": [ \
        {"email": "invited_signer@email.com", \
         "fields": [ \
          {"page": 0, \
           "rectangle": [0, 0, 200, 100], \ 
           "type": "SIGNATURE" \    
          }] \
        }] \
      }] \
    }'

$client = new DigiSignerClient('YOUR_API_KEY'); 
$request = new SignatureRequest;
  
$document = new Document('document.pdf');
$document->setSubject('My email subject');
$document->setMessage('My email message');
$request->addDocument($document);

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

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

$signatureRequest = $client->sendSignatureRequest($request);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest signatureRequest = new SignatureRequest();
 
Document document = new Document(new File("document.pdf")); 
document.setSubject("My email subject");
document.setMessage("My email message");
signatureRequest.addDocument(document);

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

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

SignatureRequest response = client.sendSignatureRequest(signatureRequest);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest signatureRequest = new SignatureRequest();

Document document = new Document("document.pdf");
document.Subject = "My email subject";
document.Message = "My email message";


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

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

signatureRequest.Documents.Add(document);

SignatureRequest response = client.SendSignatureRequest(signatureRequest);

Request parameters:

Parameter	Type	Notes
embedded (optional)	boolean	Used when you embed documents on your web site (default: false). See here for how to embed documents on your website.
redirect_for_signing_to_url (optional)	string	URL at your website to which signers will be redirected for signing
redirect_after_signing_to_url (optional)	string	URL at your website to which signers will be redirected after signing
send_emails (optional)	boolean	If invitation and notification emails are sent (default: true)
use_text_tags (optional)	boolean	If text tags in documents are converted to fields (default: false). See here for how to use text tags in your documents.
hide_text_tags (optional)	boolean	If text tags in documents are hidden (default: false)
send_documents_as_bundle (optional)	boolean	If multiple documents should be sent as one bundle (default: false)
bundle_title (optional)	string	Title under which the bundle will be sent to signers
bundle_subject (optional)	string	Subject of invitation email to sign bundle sent to invited signers
bundle_message (optional)	string	Message of invitation email to sign bundle sent to invited signers
documents[]	array	Array of documents to be signed
├ document_id	string	Document id (returned by upload request) or template id. See here for how to use templates via API.
├ title (optional)	string	Title under which the document will be sent to signers
├ subject (optional)	string	Subject of invitation email sent to invited signers
├ message (optional)	string	Message of invitation email sent to invited signers
└ signers[]	array	Array of invited signers
├ email	string	Signer email address
├ order (optional)	integer	Signing order
├ role (optional)	string	Signer role (relevant if you send out templates or use text tags)
└ fields[] (optional)	array	Array of fields that will be added for the signer to the document
├ type	string	Field type (SIGNATURE, TEXT, INITIALS, DATE, CHECKBOX)
├ page	integer	Page where the field is placed (starts from 0)
├ rectangle	array	Field coordinates (e.g. field at bottom left corner [0, 0, 200, 100])
├ api_id (optional)	string	Id that will be assigned to the field (relevant if you later will need to retrieve content entered by the signer)
├ label (optional)	string	Text to be displayed on the field as a tip for the signer
├ content (optional)	string	Text to prefill text and date fields, signer name in signature dialog and signer initials in initials dialog (content of the text tab)
├ group_id (optional)	string	Group id to combine a set of radio buttons or checkboxes in one group
├ required (optional)	boolean	If the field is required for filling in (default: true)
└ read_only (optional)	boolean	If the signer can change the field's content (default: false)
└ existing_fields[] (optional)	array	Array of existing fields for which you can set certain attributes, like content. Useful for populating template fields.
├ api_id	string	API id to identify the existing field (can be found out by requesting the list of document/template fields)
├ label (optional)	string	Text to be displayed on the field as a tip for the signer
├ content (optional)	string	Text to prefill text and date fields, signer name in signature dialog and signer initials in initials dialog (content of the text tab)
├ group_id (optional)	string	Group id to combine a set of radio buttons or checkboxes in one group
├ required (optional)	boolean	If the field is required for filling in (default: true)
└ read_only (optional)	boolean	If the signer can change the field's content (default: false)

Response

Sample response:

{"signature_request_id":"f9bf5865-de7e-4fd5-8be6-aa8d8f46735c",
 "send_emails":true,
 "embedded":false,
 "use_text_tags":false,
 "hide_text_tags":false,
 "is_completed":false,
 "documents":[
  {"signers":[
   {"email":"invited_signer@email.com",
    "is_signature_completed":false,
    "sign_document_url":"https://www.digisigner.com/online/showDocument?documentId=98d2f2cf-58e7-401e-863e-199ea29c226f&invitationId=acfe6dc3-5a07-4edb-b019-ff23e112a020"
   }],
   "document_id":"5be88823-3ff5-4ec4-8175-459dee50f7fb"
  }]
}

The response parameters duplicate the request parameters, with the exception of sign_document_url. This parameter represents the URL of the signature page to which a particular signer will be redirected to sign a specific document.

You can use sign_document_url, e.g., in the case, if you do not want DigiSigner to send invitations to signers via email (the request parameter send_emails is set to be false), but instead want your own system to send emails or even redirect the signer directly to the signature page.

See our tutorials for more information

How to Send Signature Requests – more 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 templates in GUI mode and use them via our eSignature 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

Get Signature Request Status

Returns information about a specific signature request, including the current signature status. Requires a signature_request_id.

URL

GET https://api.digisigner.com/v1/signature_requests/{signature_request_id}

Request

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

$client = new DigiSignerClient('YOUR_API_KEY'); 
$signatureRequest = $client->getSignatureRequest($signatureRequestId);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest response = client.getSignatureRequest(signatureRequestId);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
SignatureRequest response = client.GetSignatureRequest(signatureRequestId);

Response

Sample response:

{"signature_request_id":"f9bf5865-de7e-4fd5-8be6-aa8d8f46735c",
 "send_emails":true,
 "embedded":false,
 "use_text_tags":false,
 "hide_text_tags":false,
 "is_completed":false,
 "documents":[
  {"signers":[
   {"email":"invited_signer@email.com",
    "is_signature_completed":false,
    "sign_document_url":"https://www.digisigner.com/online/showDocument?documentId=98d2f2cf-58e7-401e-863e-199ea29c226f&invitationId=acfe6dc3-5a07-4edb-b019-ff23e112a020"
   }],
   "document_id":"5be88823-3ff5-4ec4-8175-459dee50f7fb"
  }]
}

Response parameters:

Parameter	Type	Notes
signature_request_id	string	Signature request id
is_completed	boolean	If all signers completed all documents
documents[]	array	Array of documents in this signature request
├ document_id	string	Document id
└ signers[]	array	Array of invited signers
├ email	string	Signer email address
├ is_signature_completed	boolean	If particular signer completed particular document
└ sign_document_url	string	URL of the DigiSigner signing page

In the response you can see if the signature request has been completed (via the parameter is_completed) and if the single signers have signed the document (via the parameter is_signature_completed).

Delete Document

Deletes document. Requires the document_id as a parameter.

URL

DELETE https://api.digisigner.com/v1/documents/{document_id}

Request

curl -X DELETE -u YOUR_API_KEY: https://api.digisigner.com/v1/documents/{document_id}

$client = new DigiSignerClient('YOUR_API_KEY'); 
$client->deleteDocument($documentId);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
client.deleteDocument(documentId);

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
client.DeleteDocument(documentId);

In the request, use the document_id that is returned by the ‘Upload Document’ request.

Response

The response has no content.

Get Document Fields

Returns information about document fields, including content entered by signers. Requires a document_id.

URL

GET https://api.digisigner.com/v1/documents/{document_id}/fields

Request

Sample request:

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

$client = new DigiSignerClient('YOUR_API_KEY'); 
$documentFields = $client->getDocumentFields($document_id);

foreach($documentFields->getDocumentFields() as $field) {    
    print("Field api id: ".$field->getApiId()."\n");              // field api_id
    print("Submitted value: ".$field->getSubmittedContent."\n");  // value entered by signer
}

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.getDocumentFields(documentId);
      
for (DocumentField field : documentFields.getDocumentFields()) {
    System.out.println("Field api id: " + field.getApiId());                // field api_id
    System.out.println("Submitted value: " + field.getSubmittedContent());  // value entered by signer
}

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");
DocumentFields documentFields = client.GetDocumentFields(documentId);

foreach (DocumentField field in documentFields.Fileds)
{
    Console.WriteLine("Field api id: " + field.ApiId);               // field api_id
    Console.WriteLine("Submitted value: " + field.SubmittedContent); // value entered by signer
}

Response

Sample response:

{"document_fields":[  
  {"api_id":"d5e0be97-0c43-4e7e-b829-c7a62accb224",
   "submitted_content":"James Williams",
   ...
  }, 
  {"api_id":"3de8121a-ca39-42fa-b5cc-32cc82301014",
   "submitted_content":"Customer Care",
   ...
  }]
}

See our tutorials for more information

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

Download Document Attachment

Downloads the content of the document attachment. Requires the document_id and field_api_id as a parameters.

URL

GET https://api.digisigner.com/v1/documents/{document_id}/fields/{field_api_id}/attachment

Request

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'); 
$client->getDocumentAttachment($documentId, $fieldApiId, 'attachment.pdf');

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
File attachment = client.getDocumentAttachment(documentId, fieldApiId, "attachment.pdf");

DigiSignerClient client = new DigiSignerClient("YOUR_API_KEY");  
client.GetDocumentAttachment(documentId, fieldApiId, "attachment.pdf");

In the request, use the document_id that is returned by the ‘Upload Document’ request. The corresponding field_api_ids can be retrieved using the Get Document Fields request. The content of the file will be saved as attachment.pdf.

Response

The response then represents the content of the requested document attachment.

Callback

You can register for notifications if you want to be notified that your signature request has been completed or your document has been signed. You must specify callback URLs in your DigiSigner account settings to accomplish the registration.

5_callback_url

DigiSigner expects the response code 200 from your callback code, and the response text should be ‘DIGISIGNER_EVENT_ACCEPTED.’ Otherwise, DigiSigner will repeat the callback request in 5, 20, 65, 200, 605 and 1820 minutes.

“Signature Request Completed” callback URL

This callback URL is called by DigiSigner when the signature request has been completed. That is when all the invited signers have signed all the documents that are part of this signature request.

Sample callback content:

{"event_time":1435228059868,
 "event_type":"SIGNATURE_REQUEST_COMPLETED",
 "signature_request":{
   "signature_request_id":"f9bf5865-de7e-4fd5-8be6-aa8d8f46735c",
   "send_emails":true,
   "embedded":false,
   "use_text_tags":false,
   "hide_text_tags":false,
   "is_completed":true,
   "documents":[
    {"signers":[{"email":"invited_signer@email.com", "is_signature_completed":true}],
     "document_id":"5be88823-3ff5-4ec4-8175-459dee50f7fb"
    }]
  }
}

Callback parameters:

Parameter	Type	Notes
event_time	string	Event timestamp
event_type	string	SIGNATURE_REQUEST_COMPLETED
signature_request	object	Signature request object
├ signature_request_id	string	Signature request id
├ send_emails	boolean	If invitation and notification emails were sent
├ embedded	boolean	If signature reques is in embedded mode
├ use_text_tags	boolean	If text tags in documents were converted to fields
├ hide_text_tags	boolean	If text tags in documents were hidden
├ is_completed	boolean	If request is completed (at this point always true)
└ documents[]	array	Array of documents in this signature request
├ document_id	string	Document id
└ signers[]	array	Array of signers for this document
├ email	string	Signer email address
└ is_signature_completed	boolean	If signer completed document (at this point always true)

“Document Signed” callback URL

This callback URL is called by DigiSigner when an invited signer has signed your document.

Sample callback content:

{"event_time":1435228059867, 
 "event_type":"DOCUMENT_SIGNED", 
 "document_id":"5be88823-3ff5-4ec4-8175-459dee50f7fb", 
 "signer_email":"invited_signer@email.com"
}

Callback parameters:

Parameter	Type	Notes
event_time	string	Event timestamp
event_type	string	DOCUMENT_SIGNED
document_id	string	Id of the signed document
signer_email	string	Signer email address

Libraries

We offer the following libraries for using our eSignature API:

DigiSigner PHP Client
DigiSigner Java Client
DigiSigner C# Client

Please don’t hesitate to contact us in case you have any questions or suggestions about using our electronic signature API.

DigiSigner eSignature API Documentation

Introduction to eSignature API

Authentication

Upload Document

Download Document

Send Signature Request

Get Signature Request Status

Delete Document

Get Document Fields

Download Document Attachment

Callback

Libraries

Company

Industry

Documentation

Tools

Legal