Envelope Statuses

Below is a list of all the statuses that could be returned as the envelope_status field

Status Definition
processing First status of the envelope, if you are sending a non-template.
sent Once the envelope has been processed
signed Once the envelope is signed and complete
cancelled When the envelope is cancelled
expired When the envelope is cancelled
failed If the envelope doesn’t complete processing
draft If the envelope has been created but not sent

Create (and send out) an envelope with a template

Arguments

Argument Required/optional Description
envelope_title required A string of the title of the new envelope
user_id optional An integer representing the ID of the user that is sending out the document. This user_id must match an existing User within Signable. This is optional.
envelope_password_protect optional A boolean, either true or false to indicate whether to send this out as a password protected document. This is optional, if left out it defaults to false.
envelope_redirect_url optional A URL that you want the signer to be redirected to when the document has been signed. This is optional, if left out it the signer will be redirected to the standard confirmation page.
envelope_auto_expire_hours optional An integer which represents when you want Signable to automatically expire the envelope if the envelope is still in progress. This value is in hours and must be greater than 12. For example setting this to 72 will automatically expire the envelope after 72 hours (3 days). This is optional, if left out the envelope isn’t automatically expired
envelope_auto_remind_hours optional An integer which represents how often you want Signable to automatically remind the active signer. This value is in hours and must be greater than 12. For example setting this to 24 will tell Signable to automatically send a reminder out every 24 hours. This is optional and if left out, no automatic reminding is performed.
envelope_meta optional A JSON string containing any additional information that you want to store, in Signable, along with the envelope. This envelope_meta data must be a JSON string and less than 2000 characters. This is optional.
envelope_documents required A JSON string containing the individual document information. This is an array of objects containing the following in each object:
– document_title required The string of the title of the document
– document_template_fingerprint required A valid fingerprint of the template you want to send out
– document_merge_fields optional A JSON string containing the merge fields for this template. This is an array of objects containing the following in each object:
– field_id required An integer representing the ID of the merge field
– field_value required A string representing the value of the merge field
envelope_parties required A JSON string containing all parties relating to this envelope. This is an array of objects containing the following in each object:
– party_name required A string of the name of the signing party
– party_email required A string of a valid email address of the party
– party_id required An integer representing the ID of the party which is setup in the template that you want to send out.
– party_role optional A string either being ‘signer’ or ‘copy’ if you want to include a party that just needs to be copied in. If left out, it will be set to ‘signer’.
– party_message optional A message which will be sent to this party when it is their turn to sign. It is shown in the email that is sent to the signing party.

Example Request

Below is an example sending out a template which has the following details:

  • Fingerprint: fd2906a685817cbeea48b5bb54169f50
  • Parties (and merge fields: party_id: 10000, party_merge_fields: field_id: 20000

cURL

curl https://api.signable.co.uk/v1/envelopes 
-u d41d8cd98f00b204e9800998ecf8427e:x 
-X POST 
-d "envelope_title=My envelope" 
-d "user_id=1234" 
-d 'envelope_documents=[{"document_title": "Test Document Title","document_template_fingerprint": "fd2906a685817cbeea48b5bb54169f50","document_merge_fields":[{"field_id": 20000,"field_value": "Test Merge"}]}]'  
-d 'envelope_parties=[{"party_name": "John Smith","party_email": "john@smith.com","party_id":10000,"party_message":"Please sign this!"}]'
		

PHP

// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$mergeFields		= array();
$mergeField          	= new Signable\MergeField( 20000, 'Test merge' );
$mergeFields[]     	= $mergeField;

$envelopeDocuments    	= array();
$envelopeDocument      = new Signable\DocumentWithTemplate( 'Test Document Title','fd2906a685817cbeea48b5bb54169f50', $mergeFields );
$envelopeDocuments[] = $envelopeDocument;
$envelopeParties       	= array();
$envelopeParty         	= new Signable\Party( 'John Smith', 'john@smith.com', 10000, 'Please sign this!','yes' );
$envelopeParties[]   	= $envelopeParty;

$response = Signable\Envelopes::createNewWithTemplate( "My Envelope", $envelopeDocuments, $envelopeParties, 1234, false, "http://redirect.me" );

// Output the response
var_dump($response);
			

Example Response

{
    "http": 202,
    "message": "Your envelope with title My envelope will be processed and sent out.",
    "href": "https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e",
    "envelope_title": "My envelope",
    "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
    "envelope_signing_embed": "<iframe src='https://app.signable.co.uk/contract/sign/1234/5678/90123/a447d6e27037fddf65a7d3f5e2c41e6c/d41d8cd98f00b204e9800998ecf8427e' width='100%' height='95%' frameborder='0' style='border: 0; overflow: hidden'></iframe>"
    "envelope_queued": "2013-10-25T13:53:49+0000"
}

 


Create (and send out) an envelope with non-template documents

Make sure you setup Signable Tags in the document before sending.

Arguments

Argument Required/optional Description
envelope_title required A string of the title of the new envelope
user_id optional An integer representing the ID of the user that is sending out the document. This user_id must match an existing User within Signable. This is optional.
envelope_password_protect optional A boolean, either true or false to indicate whether to send this out as a password protected document. This is optional, if left out it defaults to false.
envelope_redirect_url optional A URL that you want the signer to be redirected to when the document has been signed. This is optional, if left out it the signer will be redirected to the standard confirmation page.
envelope_auto_expire_hours optional An integer which represents when you want Signable to automatically expire the envelope if the envelope is still in progress. This value is in hours and must be greater than 12. For example setting this to 72 will automatically expire the envelope after 72 hours (3 days). This is optional, if left out the envelope isn’t automatically expired
envelope_auto_remind_hours optional An integer which represents how often you want Signable to automatically remind the active signer. This value is in hours and must be greater than 12. For example setting this to 24 will tell Signable to automatically send a reminder out every 24 hours. This is optional and if left out, no automatic reminding is performed.
envelope_meta optional A JSON string containing any additional information that you want to store, in Signable, along with the envelope. This envelope_meta data must be a JSON string and less than 2000 characters. This is optional.
envelope_documents required A JSON string containing the individual document information. This is an array of objects containing the following in each object:
– document_title required The string of the title of the document
– document_url optional A valid URL to either a PDF, Word or Excel file. Either document_url or document_file_content (and document_file_name) have to passed in.
– document_file_content optional A base64 encoded string of the contents of a PDF, Word or Excel file. Either document_url or document_file_content (and document_file_name) have to passed in.
– document_file_name required The string of the filename of the document, including the extension, for example ‘contract.pdf’. Either document_url or document_file_content (and document_file_name) have to passed in.
envelope_parties required A JSON string containing all parties relating to this envelope. This is an array of objects containing the following in each object:
– party_name required A string of the name of the signing party
– party_email required A string of a valid email address of the party
– party_role required A string matching the WHO part of the tags setup in the document. This needs to be either signer1, signer2, signer3 e.t.c or it can be ‘copy’ if you want to include a party that just needs to be copied in.
– party_message optional A message which will be sent to this party when it is their turn to sign. It is shown in the email that is sent to the signing party.

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes 
-u d41d8cd98f00b204e9800998ecf8427e:x 
-X POST 
-d "envelope_title=My envelope" 
-d "user_id=1234" 
-d 'envelope_documents=[{"document_title": "Test Document Title","document_url": "http://assets.signable.co.uk/SampleDoc.pdf"},{"document_title": "Test Document Title 2","document_url": "http://assets.signable.co.uk/SampleDoc.pdf"}]'  
-d 'envelope_parties=[{"party_name": "John Smith","party_email": "john@smith.com","party_role":"signer1","party_message":"Please sign this!"}]'
		

PHP

// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$envelopeDocuments    	= array();
$envelopeDocument      = new Signable\DocumentWithoutTemplate( 'Test Document Title', 'http://assets.signable.co.uk/SampleDoc.pdf', $mergeFields );
$envelopeDocuments[] = $envelopeDocument;
	
$envelopeParties       	= array();
$envelopeParty         	= new Signable\Party( 'John Smith', 'john@smith.com', 'signer1', 'Please sign this!','no' );
$envelopeParties[]   	= $envelopeParty;

$response = Signable\Envelopes::createNewWithoutTemplate( "My Envelope", $envelopeDocuments, $envelopeParties, 1234, false, "http://redirect.me" );

// Output the response
var_dump($response);
			

Example Response

{
    "http": 202,
    "message": "Your envelope with title Test Envelope Title will be processed and sent out.",
    "href": "https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e",
    "envelope_title": "My envelope",
    "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
    "envelope_queued": "2013-10-25T13:53:49+0000"
}

 


Get an envelope

Arguments

Argument Required/optional Description
envelope_fingerprint required A string indicating the fingerprint of the envelope you want to retrieve

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e
-u d41d8cd98f00b204e9800998ecf8427e:x
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::getSingle('d41d8cd98f00b204e9800998ecf8427e');
// Output the response
var_dump($response);
			

Example Response

{
    "http": 200,
    "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
    "envelope_title": "Test Envelope Title",
    "envelope_status": "sent",
    "envelope_redirect_url": "http://www.google.com",
    "envelope_created": "2013-10-17T13:17:00+0000",
    "envelope_sent": "2013-10-17T13:17:00+0000",
    "envelope_documents": [
        {
            "document_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
            "document_title": "Test Envelope Title",
            "document_page_total": "1",
            "document_pdf_url": "http://docs.signable.co.uk/original/d41d8cd98f00b204e9800998ecf8427e.pdf",
            "document_thumbnails": [
                "http://docs.signable.co.uk/small/d41d8cd98f00b204e9800998ecf8427e-0.jpg"
            ],
            "document_pages": [
                "http://docs.signable.co.uk/large/d41d8cd98f00b204e9800998ecf8427e-0.jpg"
            ],
            "document_fields": [
                {
                    "field_id": "987654321",
                    "field_title": "Date Here",
                    "field_type": "date",
                    "field_value": "01/01/2015",
                    "party_id": "1234",
                    "field_merge": null
                }
        }
    ],
    "envelope_parties": [
        {
            "party_id": "1234",
            "party_title": "John Smith",
            "party_status": "signed",
"contact_id": "9876",
      "contact_email": "john@smith.com"
        },
        {
            "party_id": "5678",
            "party_title": "Jane Smith",
            "party_status": "in progress",
"contact_id": "54321",
      "contact_email": "jane@smith.com"
        },
    ],
    "envelope_signed_pdf" : "https://app.signable.co.uk/contract/down/1000/1000/1000/d41d8cd98f00b204e9800998ecf8427e/d41d8cd98f00b204e9800998ecf8427e",
"envelope_history": [
    {
      "history_detail": "Document generated with fingerprint d41d8cd98f00b204e9800998ecf8427e.",
      "history_ip": "123.456.789.012",
      "history_user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/1.0.154.53 Safari/525.19",
      "history_date": "2016-06-29T16:31:49+0000"
    },
    {
      "history_detail": "Envelope generated.",
      "history_ip": "123.456.789.012",
      "history_user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/1.0.154.53 Safari/525.19",
      "history_date": "2016-06-29T16:31:46+0000"
    },
    {
      "history_detail": "John Smith has been assigned to this envelope.",
      "history_ip": "123.456.789.012",
      "history_user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/1.0.154.53 Safari/525.19",
      "history_date": "2016-06-29T16:31:46+0000"
    },
    {
      "history_detail": "Sent the envelope to John Smith (john@smith.com) for signing.",
      "history_ip": "123.456.789.012",
      "history_user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/1.0.154.53 Safari/525.19",
      "history_date": "2016-06-29T16:31:46+0000"
    },
    {
      "history_detail": "Document emailed to party.",
      "history_ip": "123.456.789.012",
      "history_user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/1.0.154.53 Safari/525.19",
      "history_date": "2016-06-29T16:31:56+0000"
    }
  ],
  "envelope_meta": {
    "my_value": "1234"
  }
}

 


List envelopes

Arguments

Argument Required/optional Description
offset optional A positive integer indicating the first record to retrieve. Defaults to the first envelope.
limit optional A positive integer indicating the maximum number of envelopes to return. Defaults to 10.

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes?offset=0&limit=3 
-u d41d8cd98f00b204e9800998ecf8427e:x
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::getMultiple( 0, 10 );
// Output the response
var_dump($response);
			

Example Response

{
    "http": 200,
    "offset": 0,
    "limit": 3,
    "total_envelopes": "10",
    "next": "http://api.signable.co.uk/v1/envelopes?offset=3&limit=3",
    "href": "http://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e",
    "envelopes": [
        {
            "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
            "envelope_title": "Test envelope",
            "envelope_status": "processing",
            "envelope_redirect_url": "http://www.google.com",
            "envelope_created": "2013-08-16T13:49:28+0000",
            "envelope_sent": null
        },
        {
            "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
            "envelope_title": "Test envelope",
            "envelope_status": "processing",
            "envelope_redirect_url": "http://www.google.com",
            "envelope_created": "2013-08-16T13:49:28+0000",
            "envelope_sent": null
        },
        {
            "envelope_fingerprint": "d41d8cd98f00b204e9800998ecf8427e",
            "envelope_title": "Test envelope",
            "envelope_status": "processing",
            "envelope_redirect_url": "http://www.google.com",
            "envelope_created": "2013-08-16T13:49:28+0000",
            "envelope_sent": null
        },
    ]
}

 


Send a reminder for an envelope

Arguments

Argument Required/optional Description
envelope_fingerprint required A string indicating the fingerprint of the envelope you want to remind

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e/remind \
   -u d41d8cd98f00b204e9800998ecf8427e:x \
   -X PUT \
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::sendReminder('d41d8cd98f00b204e9800998ecf8427e');
// Output the response
var_dump($response);
			

Example Response


{
	"http":200,
	"message":"The next signing party for this envelope has been reminded.",
	"envelope_fingerprint":"d41d8cd98f00b204e9800998ecf8427e",
	"envelope_title":"Envelope Title"
}

 


Cancel an envelope

Arguments

Argument Required/optional Description
envelope_fingerprint required A string indicating the fingerprint of the envelope you want to cancel

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e/cancel \
   -u d41d8cd98f00b204e9800998ecf8427e:x \
   -X PUT \
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::cancel('d41d8cd98f00b204e9800998ecf8427e');
// Output the response
var_dump($response);
			

Example Response


{
	"http":200,
	"message":"The envelope has been cancelled",
	"envelope_fingerprint":"d41d8cd98f00b204e9800998ecf8427e",
	"envelope_title":"Envelope Title"
}

 


Expire an envelope (silently cancel a document)

Arguments

Argument Required/optional Description
envelope_fingerprint required A string indicating the fingerprint of the envelope you want to expire

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e/expire \
   -u d41d8cd98f00b204e9800998ecf8427e:x \
   -X PUT \
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::expire('d41d8cd98f00b204e9800998ecf8427e');
// Output the response
var_dump($response);
			

Example Response


{
	"http":200,
	"message":"The envelope has been expired",
	"envelope_fingerprint":"d41d8cd98f00b204e9800998ecf8427e",
	"envelope_title":"Envelope Title"
}

 

Delete or remove an envelope

Arguments

Argument Required/optional Description
envelope_fingerprint required A string indicating the fingerprint of the envelope you want to delete

Example Request

cURL

curl https://api.signable.co.uk/v1/envelopes/d41d8cd98f00b204e9800998ecf8427e \
   -u d41d8cd98f00b204e9800998ecf8427e:x \
   -X DELETE \
		

PHP


// Download our PHP SDK Library here: https://github.com/Signable/signable-sdk-php
$response = Signable\Envelopes::delete('d41d8cd98f00b204e9800998ecf8427e');
// Output the response
var_dump($response);
			

Example Response


{
	"http":200,
	"message":"The envelope has been deleted",
	"envelope_fingerprint":"d41d8cd98f00b204e9800998ecf8427e",
	"envelope_title":"Envelope Title"
}