Breadcrumbs

Request signature

Request signature from one or more signatories.

JavaScript
POST /share?token=:authenticationToken

  • Shares the document to other users to sign it = request signature from other parties

  • In case of external user, you can protect the share using either password or OTP.

    • In case of OTP you have to specify recipient phone number or email, on which the authentication code will be sent.

  • If you select multiple participants, you can choose whether they have to sign the document sequentialy (one-by-one) or they can sign it at once.

    • If sequential signing is set to true and the order is not specified, it will be taken from the data property

  • You can choose one of sign types: signature, initials, stamp, wacom, annotation, and image

  • Participants get notification or e-mail with link to access the document.

  • to see which user(s) are required to sign (all who did not sign yet) use below call

    JavaScript
    GET /documents/{docID}

and the user(s) are specified in response object - value waitingFor

Example

In example below we are requesting a signature from an external user (bill.taylor789@gmail.com) and a stamp from an internal user (kim.black@circularo.com).

The document is secured by phone OTP for the external user and Bill will be signing on the 3rd page while Kim will place her stamp on the 4th page.

The signing will happen sequentially, with Bill signing first and then Kim will be notified to place a stamp.

Request

JavaScript
POST /share/?token=ADFFQBYXP2NVGR6PAP3KOR27FETP6
{
    "objectType": "document",
    "type": "d_default",
    "id": "d148b19a-4fa9-442e-adfd-7aa68b8eb766", //document id
    "data": [ //specify at least one participant
        {
            "sharePurpose": "sign",
            "shareTo": "bill.taylor789@gmail.com",  //external user
            "message": "Sign me",  //optional private message
            "validUntil": "2020-02-11T19:10:10.100Z",   //optional expiration date in ISO 8601 format
            "otpEnabled": true, //or use password or leave unsecured = optional field
            "phone": "4453217784"   //OTP phone number, or use e-mail address instead

        }, {
            "sharePurpose": "sign",
            "shareTo": "kim.black@circularo.com",  //internal username
            "message": "Sign me, please", //optional private message
            "validUntil": "2020-02-12T19:10:10.100Z" //optional expiration date in ISO 8601 format
        }
    ],
    "signatureFields": [
        {
            "user": ["bill.taylor789@gmail.com"],
            "timestamp": false,
            "required": true,
            "tooltip": "Signature tooltip text",
            "type": "signature",    //sign type
            "pages": [3],  //document page with signature
            "position": {   //position and size of the signature in the document page
                "percentX": 0.5,
                "percentY": 0.1,
                "percentWidth": 0.2,
                "percentHeight": 0.05
            }
        }, {
            "user": ["kim.black@circularo.com"],
            "timestamp": true,
            "required": true,
            "tooltip": "Stamp tooltip text",
            "type": "stamp",    //sign type is stamp
            "pages": [4],
            "position": { //position and size of the signature in the document page
                "percentX": 0.3,
                "percentY": 0.65,
                "percentWidth": 0.15,
                "percentHeight": 0.15
            }
        }
    ],
    "sequential": true  //recipients are required to sign one-by-one
}

Response

JavaScript
[
    {
        "shareId": "7d746a2d9fd447b11bb870b69192df8c0933892aba0c2d15468ed85d79095948",
        "isActive": true,
        "shareDate": "2020-02-11T16:16:16.150Z",
        "shareType": "sign",
        "sharedBy": "judy.corbett",
        "sharedObjectEsId": "d148b19a-4fa9-442e-adfd-7aa68b8eb766",
        "sharedObjectEsType": "d_default",
        "sharedObjectType": "document",
        "sharedWith": [ "bill.taylor789@gmail.com" ],
        "otpEnabled": true,
        "otpPhone": "**84"
        "passwordRequired": false,
        "privateMessage": "Sign me",
        "validUntil": "2020-02-11T19:10:10.100Z",
        "sequential": true
    }, {
        "shareId": "7a9p0ac5a2qkgis1am9nix37wifhryj4g5sdhtux578qwel0cposx51asurt23qe",
        "isActive": true,
        "shareDate": "2020-02-11T16:16:16.150Z",
        "shareType": "sign",
        "sharedBy": "judy.corbett@circularo.com",
        "sharedObjectEsId": "d148b19a-4fa9-442e-adfd-7aa68b8eb766",
        "sharedObjectEsType": "d_default",
        "sharedObjectType": "document",
        "sharedWith": [ "kim.black@circularo.com" ],
        "otpEnabled": false,
        "passwordRequired": false,
        "sharedUsername": "kim.black@circularo.com",
        "privateMessage": "Sign me, please",
        "validUntil": "2020-02-11T19:10:10.100Z",
        "sequential": true
    }
]