Create a Signing Session Invite with Fields

Last updated on 2017-08-31 11:40:47

This article describes how to use the evaluation API environment to create a document, create an invitation to sign that document, and provide a signing link to the document invite.

The instructions in this article use the Evaluation API infrastructure only. None of the information or records created here are guaranteed available for more than 48 hours. No SignNow accounts or data are available in the Evaluation infrastructure. Contact your account manager for access to the SignNow production API.

This tutorial assumes some familiarity with REST API calls, the unix/linux command line tool 'curl' or similar tools that create https requests, and the JSON data format.

Use the steps in this article when using the SignNow API to build embedded signing sessions directly into your web or mobile applications. Create a single recipient account that you can reuse for every signing event; multiple recipient accounts are unnecessary.

You can cancel and resend invites if an email address or document changes via API calls or directly in the web interface.

PART 1: One-Time Setup

Part 1 describes a one-time setup process; you need complete these steps only once.

Step 1. Obtain Valid Client Application Details

To obtain access to the Eval API environment, go to https://university.signnow.com/api/ and complete the form. You will receive a ClientID and ClientSecret, as well as ENCODED_CLIENT_CREDENTIALS, which will provide access to the Eval API environment.

For Production access and pricing information, contact SignNow in one of the following ways:

800-231-2050
Request a call back at https://university.signnow.com/contactus/
Email us at signnowpremium@barracuda.com

Step 2. Create Sender Account

Go to https://eval.signnow.com/signup
Sign up for a new account, and make note of your email address and password, to use in place of USER_1_EMAIL and USER_1_PASSWORD below.

Step 3. Get Access Token for First User

curl -H 'Authorization: Basic ENCODED_CLIENT_CREDENTIALS' --data 'username=USER_1_EMAIL&password=USER_1_PASSWORD&grant_type=password' https://api-eval.signnow.com/oauth2/token

Make a note of the access token you receive: ( USER_1_ACCESS_TOKEN )

Step 4. Create a Signer Account

Only one account is needed as it will be re-used for every signing event. Go to: https://eval.signnow.com/signup

Sign up for a new account and make a note of your email address and password which are in the form USER_2_EMAIL and USER_2_PASSWORD below. Be sure to verify the email.

Step 5. Get the Signer Account Access Token

curl -H 'Authorization: Basic ENCODED_CLIENT_CREDENTIALS' --data 'username=USER_2_EMAIL&password=USER_2_PASSWORD&grant_type=password' https://api-eval.signnow.com/oauth2/token

Make a note of the access token you receive: ( USER_2_ACCESS_TOKEN )

Step 6. Edit Signer Account Name

Edit the first and last name of the signer account, and turn off reusable signatures. This appears in the document signing process for your users. We suggest "Guest Signer". Make the following PUT call to accomplish this:

curl -H 'Authorization: Bearer USER_2_ACCESS_TOKEN' --data '{"first_name":"Guest","last_name":"Signer"}' https://api-eval.signnow.com/user

Turn off reusable signatures:

curl -X PUT -H 'Authorization: Bearer USER_2_ACCESS_TOKEN' --data '{"active":1}' https://api-eval.signnow.com/user/setting/no_user_signature_return

Part 2: Repeatable Process for Every Document

The steps in Part 2 describe how to upload new documents and generate a unique signing link for those documents.

Step 1. Create Document as First User

There are three methods:

Method 1: Use a template that has been previously created in your account. To do this go to https://eval.signnow.com/login, log in with your credentials for this account, upload a document, and turn it into a template as shown here: https://university.signnow.com/web-help/#creating-template . Add one role to the template, name the role "Buyer" and place signature, text, and other fields as needed on this template. Get the template_id ( USER_1_TEMPLATE_ID ) as described here: https://university.signnow.com/web-help/#creating-template . Then, to create a document from the template, use this CURL call:

curl -H 'Authorization: Bearer USER_1_ACCESS_TOKEN' https://api-eval.signnow.com/template/USER_1_TEMPLATE_ID/copy

This will return a document ID.

Method 2: Upload a document with text tags on it. Click here to download an example.

For more information, see How to Generate Text Tags on a Document.

Use the following curl call to upload the document. This will auto-convert text tags to fields:

curl -H 'Authorization: Bearer USER_1_ACCESS_TOKEN' -F 'file=@FILE_NAME' https://api-eval.signnow.com/document

This will return a document ID.

Method 3: Upload a plain document and then put fields on it using the API.

curl -H 'Authorization: Bearer USER_1_ACCESS_TOKEN' -F 'file=@FILE_NAME' https://api-eval.signnow.com/document

This returns the document ID, then do a PUT to place fields on the document; adjust the x,y coordinates to place the signature field where needed:

curl -X PUT -H 'Authorization: Bearer ACCESS_TOKEN' --data '{"fields":[{"x":305,"y":18,"width":122,"height":34,"page_number":0,"role":"Buyer","required":true,"type":"signature"}]}' https://api-eval.signnow.com/document/DOCUMENT_ID

Step 2. Create Invite to Sign Uploaded Document

Make a POST /document//invite call, with email=disable to suppress the delivery of an email invite:

curl -H 'Authorization: Bearer ACCESS_TOKEN' --data '{"to":[{"email":"USER_2_EMAIL","role":"Buyer","order":1, "role_id":""}],"from":"USER_1_EMAIL","cc":[],"subject":"Please Sign","message":"Please Sign"}' https://api-eval.signnow.com/document/DOCUMENT_ID/invite?email=disable

Step 3. Generate Restricted Scope Access Token for Signing Link

For document_id, use the document ID generated in the preceding section.

Get an access_token with a scope specific to that document by making a POST /oauth2/token request for USER_2:

curl -H 'Authorization: Basic ENCODED_CLIENT_CREDENTIALS' --data 'username=USER_2_EMAIL&password=USER_2_PASSWORD&grant_type=password&scope=signer_limited_scope_token document/DOCUMENT_ID' https://api-eval.signnow.com/oauth2/token

This returns USER_2_RESTRICTED_ACCESS_TOKEN

Step 4. Generate Full Signing Link

The base URL for the link is: https://eval.signnow.com/dispatch?route=assign

The link requires the query parameters: document_id and access_token

https://eval.signnow.com/dispatch?route=fieldinvite&document_id=DOCUMENT_ID&access_token=USER_2_RESTRICTED_ACCESS_TOKEN

The signing link accepts optional query parameters

redirect_uri

theme

disable_email

To use a neutral theme, send the user to a simple thank you page after they have successfully completed the signing session, suppress the sending of the signed document via email, and add this item to the query string:

redirect_uri=%2Fdocument-saved-successfully&theme=neutral&disable_email=true

The full link will then be:

https://eval.signnow.com/dispatch?route=fieldinvite&document_id=DOCUMENT_ID&access_token=USER_2_RESTRICTED_ACCESS_TOKEN&redirect_uri=%2Fdocument-saved-successfully&theme=neutral&disable_email=true

Alternative Signing Link

This signing link automatically provides a mobile app signing link for iOS and Android device users:

https://eval.signnow.com/app/session/DOCUMENT_ID?access_token=USER_1_RESTRICTED_ACCESS_TOKEN

Optional Parameters

redirect_uri=%2Fdocument-saved-successfully

If a user is signing from a mobile device, add the following to direct the user to the mobile web (if the user is on a desktop system, they are automatically directed to desktop signing):
mobileweb=mobileweb_only

To allow users to sign using the mobileweb signature panel, add:

&use_signature_panel=1

Full URL

Example full URL including mobileweb and signature panel parameters:

https://eval.signnow.com/app/session/d9a500741e0ffd412d3b06e35dec4d14d7fa40b2?access_token=fec20321cc3f2a69b052bc475d1824df898322cac51062b3528e8ddeb971dc4b&mobileweb=mobileweb_only&use_signature_panel=1