Skip to navigation
How-to guidesHost the signing experience (embedded signing)

How to request a signature through your app

View as Markdown

This topic demonstrates how to collect signatures directly within your app, without emailing the signer or directing them to an external URL. This process is called embedded signing. This topic also demonstrates how to use AutoPlace to automatically position tabs in a document with a specified string.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{CLIENT_USER_ID}A string value that serves as an identifier of an individual signer throughout the signing process. The combination of this value, the signer’s name, and the signer’s email is used to uniquely identify them.
Document to be signedYou must provide at least one document to be signed. Document used in this how-to:
Return URLA URL to which the user will be forwarded after signing is complete.
{SIGNER_EMAIL}A string value for the email address where the signer will receive a notification of the signing request.
{SIGNER_NAME}A string value for the full name of the signer.

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Create the envelope definition

The first step in requesting a signature within your app is to define a method (called makeEnvelope in our example) that creates the envelope definition using the following steps:

  • Add a document to the definition by saving it to a variable as a binary-encoded base64 string. If you intend to attach multiple documents, specify the document order using an array. The order of the array sets the order of the documents.

  • Set the signer’s data, including their name, email address, and a client user ID (any alphanumeric value is suitable). Including a client user ID automatically specifies the signer as embedded (using your app). If there are multiple signers, you must create a signer recipient for each one.

    Note: If the client user ID is set and either the SignerMustHaveAccount or SignerMustLoginToSign property of the account settings is set to true, the system throws an error.

  • Create and assign signable fields (also known as tabs) for a specific signer within the document using AutoPlace. This how-to uses anchor tabs to generate tabs automatically in your document by searching for each occurrence of a specific string of characters in the document and adding tabs at those locations. This example uses the string “/sn1/” for auto-placing the signature (signHere) tab.

    To configure the anchor tabs, specify the number of units from the anchor text to offset the tab, as well as the string to search for and replace with a signHereTab within your document. You can create multiple signHere tabs for different locations and offsets, if needed.

    After creating the tabs, assign them to the signer created in the previous step.

  • Set the envelope’s status property. To save the envelope as a draft, set status to created. To configure the envelope to be sent immediately after it is instantiated, set status to sent instead.

printf \
'{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "' > $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "name": "Lorem Ipsum",
            "fileExtension": "pdf",
            "documentId": "1"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "'"${SIGNER_EMAIL}"'",
                "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "clientUserId": "1000",
                "tabs": {
                    "signHereTabs": [
                        {
                            "anchorString": "/sn1/",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}' >> $request_data

Step 3. Call Docusign to create the envelope

With the envelope definition and the attributes defined for the signer, document, and custom fields, you can now use the Envelopes:create endpoint to create an envelope for the transaction.

  • First, instantiate a new instance of the API client (if you’re using a Docusign SDK).
  • Set the following default request header to add your access token to all API calls. "Authorization: Bearer ${ACCESS_TOKEN}"
  • Initialize the Envelopes API.
  • Using your Docusign integration key and the prepared envelope definition, generate and retrieve an envelope ID using the Envelopes:create endpoint.
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes \
     --output ${response}

Step 4. Create the recipient view definition

The recipient view is the screen that Docusign generates and displays in your app to enable your signers to sign documents. To create the definition, you must add the signer’s information and the return URL.

  • Set the return URL to which the user will be forwarded after signing is complete.
  • Add the recipient information to the view, including the signer’s email, name, and clientUserID that were set for the recipient who will sign the envelope.
printf \
'{
    "returnUrl": "http://httpbin.org/get",
    "authenticationMethod": "none",
    "email": "'"${SIGNER_EMAIL}"'",
    "userName": "'"${SIGNER_NAME}"'",
    "clientUserId": 1000,
}' >> $request_data

Step 5. Create the recipient view and initiate embedded signing

Next, create the recipient view. Use the EnvelopeViews:createRecipient method, passing in your API account ID and the envelopeId and viewRequest objects generated in previous steps.

Finally, extract the URL for embedded signing, which is the value of the Url key from the JSON response. You can redirect your app’s internal browser to this URL to begin signing.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes/${envelope_id}/views/recipient \
     --output ${response})

Expected response

Use the return URL in the JSON response to start the embedded signing session in your browser.

Sample response
{
  "url": "https://demo.docusign.net/Signing/MTRedeem/v1/54984548-xxxx-xxxx-xxxx-cd0772818bbf?slt=eyJ0eX...m87j8w"
}

Next steps