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

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}

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" \    
          }] \
        }] \
      }] \
    }'

Request parameters:

ParameterTypeNotes
embedded (optional)booleanUsed 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)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). See here for how to use text tags in your documents.
hide_text_tags (optional)booleanIf text tags in documents are hidden (default: false)
send_documents_as_bundle (optional)booleanIf multiple documents should be sent as one bundle (default: false)
bundle_title (optional)stringTitle under which the bundle will be sent to signers
bundle_subject (optional)stringSubject of invitation email to sign bundle sent to invited signers
bundle_message (optional)stringMessage of invitation email to sign bundle sent to invited signers
documents[]arrayArray of documents to be signed

├ document_id

stringDocument id (returned by upload request) or template id. See here for how to use templates via API.

├ title (optional)

stringTitle under which the document will be sent to signers

├ 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

├ email

stringSigner email address

├ order (optional)

integerSigning order

├ role (optional)

stringSigner role (relevant if you send out templates or use text tags)

└ fields[] (optional)

arrayArray of fields that will be added for the signer to the document

├ type

stringField type (SIGNATURE, TEXT, INITIALS, DATE, CHECKBOX)

├ page

integerPage where the field is placed (starts from 0)

├ rectangle

arrayField coordinates (e.g. field at bottom left corner [0, 0, 200, 100])

├ api_id (optional)

stringId that will be assigned to the field (relevant if you later will need to retrieve content entered by the signer)

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

├ group_id (optional)

stringGroup id to combine a set of radio buttons or checkboxes in one group

├ required (optional)

booleanIf the field is required for filling in (default: true)

└ read_only (optional)

booleanIf the signer can change the field's content (default: false)

└ existing_fields[] (optional)

arrayArray of existing fields for which you can set certain attributes, like content. Useful for populating template fields.

├ api_id

stringAPI id to identify the existing field (can be found out by requesting the list of document/template fields)

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

├ group_id (optional)

stringGroup id to combine a set of radio buttons or checkboxes in one group

├ required (optional)

booleanIf the field is required for filling in (default: true)

└ read_only (optional)

booleanIf 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

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:

ParameterTypeNotes
signature_request_idstringSignature request id
is_completedbooleanIf all signers completed all documents
documents[]arrayArray of documents in this signature request

├ document_id

stringDocument id

└ signers[]

arrayArray of invited signers

├ email

stringSigner email address

├ is_signature_completed

booleanIf particular signer completed particular document

└ sign_document_url

stringURL 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}

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

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

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

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.

5_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_id

stringSignature request id

├ send_emails

booleanIf invitation and notification emails were sent

├ embedded

booleanIf signature reques is in embedded mode

├ use_text_tags

booleanIf text tags in documents were converted to fields

├ hide_text_tags

booleanIf text tags in documents were hidden

├ is_completed

booleanIf request is completed (at this point always true)

└ documents[]

arrayArray of documents in this signature request

├ document_id

stringDocument id

└ signers[]

arrayArray of signers for this document

├ email

stringSigner email address

└ is_signature_completed

booleanIf 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 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.

Menu