logo
theme
HelloSign
FREE
By hellosign
Updated a year ago
HelloSign Overview

Signatures. Made simple.
Getting documents signed has never been simpler. We've removed paper entirely from the process and built tools to facilitate document signing, tracking and management. Notifications keep you apprised of the signer's activity and our audit trail logs it. Once completed, signed documents are securely stored and accessible from the cloud so you can always get to your important documents.

Sharing is just as easy. With HelloSign you can share templates and signed documents with your team, other internal departments and even outside counsel, so everyone is on the same paperless page.

provider
rating
add first rating
Followers on API
Follow this API
resourcesProvider WebsiteTerms of Service
More Details

Overview

Source

Electronic Signature API Examples | HelloSign

Sending a Signature Request

There are two ways to send a Signature Request using the HelloSign API.

Signature Page Template (formerly Reusable Form)

API Method
signaturerequest/send signaturerequest/sendwithreusable_form

Prior Setup
None. Just attach your files with the API request and we'll append a signature page with a place for each person to sign.
Create a Template (formerly known as a Reusable Form) on the HelloSign site at https://www.hellosign.com/home/createTemplate.

Fields available
1 Signature field per signer.
As many text, signature, initials, checkmark and date fields as required.

Placement
Fields are placed on a separate page appended to your documents.
Fields are placed inline over the document (wherever you put them).

Dynamic Custom Fields
N / A
When setting up your Template, you can place Custom Fields on the document. Each field must be named.

When sending the Signature Request using the API, you can fill in each Custom Field with a value. These values will be shown to the signer(s) in the location that you placed that Custom Field. The signer(s) will not be able to edit them.

See the Creating a Template section for more details.

Signature Page

Let's try it out:

curl -u '[email protected]:password' 'https://api.hellosign.com/v3/signature_request/send' \
    -F 'title=NDA with Acme Co.' \
    -F 'subject=The NDA we talked about' \
    -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
    -F 'signers[0][email_address][email protected]' \
    -F 'signers[0][name]=Jack' \
    -F 'signers[1][email_address][email protected]' \
    -F 'signers[1][name]=Jill' \
    -F 'file[0][email protected]' \
    -F 'file[1][email protected]'

Response:

{
    "signature_request": {
        "signature_request_id": "ed5c515a791db8459a682418367d97d8f7f2c1e4",
        "title": "NDA with Acme Co.",
        "subject": "NDA with Acme Co.",
        "message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
        "is_complete": false,
        "has_error": false,
        "custom_fields": [
        ],
        "response_data": [
        ],
        "signing_url": "https:\/\/www.hellosign.com\/editor\/sign?guid=ed5c515a791db8459a682418367d97d8f7f2c1e4",
        "details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=ed5c515a791db8459a682418367d97d8f7f2c1e4",
        "requester_email_address": "[email protected]",
        "signatures": [
            {
                "signer_email_address": "[email protected]",
                "signer_name": "Jack",
                "order": null,
                "status_code": "awaiting_signature",
                "signed_at": null,
                "last_viewed_at": null,
                "last_reminded_at": null
            },
            {
                "signer_email_address": "[email protected]",
                "signer_name": "Jill",
                "order": null,
                "status_code": "awaiting_signature",
                "signed_at": null,
                "last_viewed_at": null,
                "last_reminded_at": null
            }
        ],
        "cc_email_addresses": [
        ]
    }
}

This will generate and send a Signature Request to both [email protected] and [email protected]

Template

Before sending a Template (formerly known as a Reusable Form) via the API you'll first need to create the Template on the HelloSign site.

Creating a Template through hellosign.com

  1. Go to .
  2. Upload a document.
  3. Specify roles for each signer for example 'Client' and 'Me'.

  1. Click "Prepare Documents"
  2. Add fields to be filled out by each role by dragging from the 'Assign Tasks' section.

  1. Add fields for any text or checkmark annotations you'll want to make at the time of sending. These are referred to by the API as Custom Fields. For example, if you wanted to add a uniquely identifying contract number to the top of each contract, you could add a text field named "contract number" and specify a different contract number to be filled in every time you send the document.

  1. Save and click Create Template

Finding the reusableformid from hellosign.com

We'll need to tell the API which Template to send and for that we need it's reusableformid. Find the Template on the Documents page and click to select it. The ID is listed in the slide out info panel.

NOTE: The ID will only show up once you have made at least one API request. The easiest call to make is probably a GET /account.

Finding the reusableformid with the API

To find the reusableformid via the API call reusable_form/list and find the object with the title and roles you supplied.

curl -u '[email protected]:password' 'https://api.hellosign.com/v3/reusable_form/list'
#For formatted JSON output try: curl -u '[email protected]:password' 'https://api.hellosign.com/v3/reusable_form/list' | python -mjson.tool"


{
    "list_info": {
        "num_pages": 1,
        "num_results": 1,
        "page": 1,
        "page_size": 20
    },
    "reusable_forms": [
        {
            "accounts": [
                {
                    "account_id": "c82e1992b64ba763e6716a05a0860f47e67ea6ee",
                    "email_address": "[email protected]"
                }
            ],
            "cc_roles": [],
            "documents": [
                {
                    "index": 0,
                    "name": "mutual_nda.pdf"
                    "form_fields": [
                        {
                            "name": "VendorName",
                            "type": "text",
                            "x": 160,
                            "y": 141,
                            "width": 80,
                            "height": 30,
                            "required": true
                        },
                        {
                            "name": "VendorTitle",
                            "type": "text",
                            "x": 160,
                            "y": 181,
                            "width": 80,
                            "height": 30,
                            "required": true
                        },
                        {
                            "name": "ManagerName",
                            "type": "text",
                            "x": 160,
                            "y": 221,
                            "width": 80,
                            "height": 30,
                            "required": true
                        },
                        {
                            "name": "ManagerTitle",
                            "type": "text",
                            "x": 160,
                            "y": 251,
                            "width": 80,
                            "height": 30,
                            "required": true
                        },
                        {
                            "name": "DateSigned",
                            "type": "date_signed",
                            "x": 523,
                            "y": 28,
                            "width": 105,
                            "height": 16,
                            "required": true
                        }
                    ],
                    "custom_fields": [
                        {
                            "name": "contract number",
                            "type": "text"
                        }
                    ],
                }
            ],
            "message": "",
            "reusable_form_id": "5eb54aaaa71ce8dcaec5d06e93a2754af1712606",
            "signer_roles": [
                {
                    "name": "Client",
                    "order": null
                },
                {
                    "name": "Me",
                    "order": null
                }
            ],
            "title": "Demo Form"
        }
    ]
}

Sending a Signature Request with a Template

curl -u '[email protected]:password' 'https://api.hellosign.com/v3/signature_request/send_with_reusable_form' \
    -F 'title=NDA with Acme Co.' \
    -F 'subject=The NDA we talked about' \
    -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
    -F 'signers[Me][email_address][email protected]' \
    -F 'signers[Me][name]=Jack' \
    -F 'signers[Client][email_address][email protected]' \
    -F 'signers[Client][name]=Jill' \
    -F 'custom_fields[contract number]=DD21' \
    -F 'reusable_form_id=5eb54aaaa71ce8dcaec5d06e93a2754af1712606'

Response:

{
    "signature_request": {
        "cc_email_addresses": [],
        "custom_fields": [
            {
                "name": "contract number",
                "value": "DD21",
                "type": "text"
            }
        ],
        "details_url": "https://www.hellosign.com/home/manage?locate=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
        "has_error": false,
        "is_complete": false,
        "message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
        "requester_email_address": "[email protected]",
        "response_data": [],
        "signature_request_id": "961f25267c4ee995619f1e28f0fcb28d2b68b84d",
        "signatures": [
            {
                "last_reminded_at": null,
                "last_viewed_at": null,
                "order": null,
                "signed_at": null,
                "signer_email_address": "[email protected]",
                "signer_name": "Jack",
                "status_code": "awaiting_signature"
            },
            {
                "last_reminded_at": null,
                "last_viewed_at": null,
                "order": null,
                "signed_at": null,
                "signer_email_address": "[email protected]",
                "signer_name": "Jill",
                "status_code": "awaiting_signature"
            }
        ],
        "signing_url": "https://www.hellosign.com/editor/sign?guid=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
        "subject": "The NDA we talked about",
        "title": "NDA with Acme Co."
    }
}

[email protected] and [email protected] will receive an email shortly. When they click on the link in the email they will be brought straight to the Document to sign.

Retrieving the signed document

Once they have signed the document you can download the final PDF using the API.

Downloading the signed PDF

curl -o mySignedPDF.pdf "https://api.hellosign.com/v3/signature_request/final_copy/961f25267c4ee995619f1e28f0fcb28d2b68b84d" -u "[email protected]:password"

Finding out when documents have been signed

There are 2 ways get the status of a document. The preferred method is to provide a callback url which we'll post events to. The option to poll the API is also available but it's impractical in most situations because of the amount of time things like signature requests can take to complete.

Webhooks (preferred)

Setting your callback url

curl -u '[email protected]:password' 'https://api.hellosign.com/v3/account' \
    -F 'callback_url=http://example.com/my_HelloSign_webhook_endpoint'

Response:

{
    "account": {
        "account_id": "c82e1992b64ba763e6716a05a0860f47e67ea6ee",
        "callback_url": "http://example.com/hellosign_callback_script.php",
        "email_address": "[email protected]",
        "role_code": null
    }
}

Handling callbacks

When events (signature request sent, signature request viewed, signature request signed, etc) are triggered we'll send a POST request to your callback url. The 'json' param will be populated with a JSON string containing an Event object as well as any relevant model objects structured like this:

{
    "event": {
        "event_time": "1348177752",
        "event_type": "signature_request_sent"
    },
    "signature_request": {
        "cc_email_addresses": [],
        "custom_fields": [],
        "details_url": "https://www.hellosign.com/home/manage?locate=1f8c510a38edbdf97eed524fba1c9a900feb56a4",
        "has_error": false,
        "is_complete": false,
        "message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
        "requester_email_address": "[email protected]",
        "response_data": [],
        "signature_request_id": "1f8c510a38edbdf97eed524fba1c9a900feb56a4",
        "signatures": [
            {
                "last_reminded_at": null,
                "last_viewed_at": null,
                "order": null,
                "signed_at": null,
                "signer_email_address": "[email protected]",
                "signer_name": "Jack",
                "status_code": "awaiting_signature"
            }
        ],
        "signing_url": "https://www.hellosign.com/editor/sign?guid=1f8c510a38edbdf97eed524fba1c9a900feb56a4",
        "subject": "NDA with Acme Co.",
        "title": "NDA with Acme Co."
    }
}

NOTE: Your endpoint will need to return a 200 HTTP code and a response body containing the following text: Hello API Event Received. Otherwise, the callback will be considered a failure and will be retried later.

Polling

Warning

Signature Requests can take days to complete, especially with multiple signers. If you poll, any frequency you choose has disadvantages, either having to make thousands of requests per signature request over a day or two or making fewer requests and having more time pass between the signature request completion and your system finding out about it. Webhooks solve both of these problems.

Checking the status of a Signature Request

curl -u "[email protected]:password" "https://api.hellosign.com/v3/signature_request/961f25267c4ee995619f1e28f0fcb28d2b68b84d"

Response:

{
    "signature_request": {
        "cc_email_addresses": [],
        "custom_fields": [],
        "details_url": "https://www.hellosign.com/home/manage?locate=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
        "has_error": false,
        "is_complete": true,
        "message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
        "requester_email_address": "[email protected]",
        "response_data": [],
        "signature_request_id": "961f25267c4ee995619f1e28f0fcb28d2b68b84d",
        "signatures": [
            {
                "last_reminded_at": null,
                "last_viewed_at": null,
                "order": null,
                "signed_at": 1348092474,
                "signer_email_address": "[email protected]",
                "signer_name": "Jack",
                "status_code": "signed"
            },
            {
                "last_reminded_at": null,
                "last_viewed_at": null,
                "order": null,
                "signed_at": 1348092432,
                "signer_email_address": "[email protected]",
                "signer_name": "Jill",
                "status_code": "signed"
            }
        ],
        "signing_url": null,
        "subject": "The NDA we talked about",
        "title": "The NDA we talked about"
    }
}
Have a question about this API?Ask the API Provider.
Developers who viewed HelloSign also viewed

Install SDK for (Node.js)Unirest

OAuth2 Authentication
Client ID
Client Secret
OAuth2 Authentication