DigiSigner API Documentation

Introduction

We provide a REST API built on pragmatic RESTful design principles using simple and modern technologies. Our 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 API.

Authentication

Our 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 API immediately.

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

How to Find Settings Settings Dialog

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

Please note that the initial API mode is TEST. In TEST mode, a watermark is automatically added to all uploaded documents. We will switch you to PROD mode when you purchase one of our DigiSigner API subscriptions.

Upload Document

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

If you are using our PHP or Java client libraries, you can skip this step and begin sending a signature request immediately. The PHP or Java 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); 
            

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");
            

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);
            

Request parameters:

ParameterTypeNotes
embedded (optional)booleanUsed when you embed documents on your web site (default: false)
redirect_for_signing_to_url (optional)stringURL at your website to which signers will be redirected for signing
redirect_after_signing_to_url (optional)stringURL at your website to which signers will be redirected after signing
send_emails (optional)booleanIf invitation and notification emails are sent (default: true)
use_text_tags (optional)booleanIf text tags in documents are converted to fields (default: false)
hide_text_tags (optional)booleanIf text tags in documents are hidden (default: false)
documents[]arrayArray of documents to be signed
├ document_idstringDocument id (returned by upload request)
├ subject (optional)stringSubject of invitation email sent to invited signers
├ message (optional)stringMessage of invitation email sent to invited signers
└ signers[]arrayArray of invited signers
├ emailstringSigner email address
├ role (optional)stringSigner role (relevant if you are using text tags)
└ fields[] (optional)arrayArray of fields the signer should to fill in
├ typestringField type (SIGNATURE, TEXT, INITIALS, DATE, CHECKBOX)
├ pageintegerPage where the field is placed (starts from 0)
├ rectanglearrayField coordinates (e.g. field at bottom left corner [0, 0, 200, 100])
├ label (optional)stringText to be displayed on the field as a tip for the signer
├ content (optional)stringText to prefill text and date fields, signer name in signature dialog and signer initials in initials dialog (content of the text tab)
└ required (optional)booleanIf field is required for filling in (default: true)

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":"http://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.

Get Signature Request Status

Returns information about a specifc 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: https://api.digisigner.com/v1/signature_requests/{signature_request_id}            
            
$client = new DigiSignerClient('YOUR_API_KEY'); 
$signatureRequest = $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":"http://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:

ParameterTypeNotes
signature_request_idstringSignature request id
is_completedbooleanIf all signers completed all documents
documents[]arrayArray of documents in this signature request
├ document_idstringDocument id
└ signers[]arrayArray of invited signers
├ emailstringSigner email address
├ is_signature_completedbooleanIf particular signer completed particular document
└ sign_document_urlstringURL 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).

Callback

If you need to be informed about the completion of the signature request, you can register for an event notification. To accomplish this, a callback URL must be specified in your DigiSigner account settings.

Callback URL

The callback URL will be automatically called by DigiSigner when the signature request has been completed, that is, when all the documents have been signed by all the invited signers.

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:

ParameterTypeNotes
event_timestringEvent timestamp
event_typestringCan be now only SIGNATURE_REQUEST_COMPLETED
signature_requestobjectSignature request object
├ signature_request_idstringSignature request id
├ send_emailsbooleanIf invitation and notification emails were sent
├ embeddedbooleanIf signature reques is in embedded mode
├ use_text_tagsbooleanIf text tags in documents were converted to fields
├ hide_text_tagsbooleanIf text tags in documents were hidden
├ is_completedbooleanIf request is completed (at this point always true)
└ documents[]arrayArray of documents in this signature request
├ document_idstringDocument id
└ signers[]arrayArray of signers for this document
├ emailstringSigner email address
└ is_signature_completedbooleanIf signer completed document (at this point always true)

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.

Libraries

We offer the following libraries for using our API:

DigiSigner PHP Client

DigiSigner Java Client

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