Features - Docs

User sends an Invite → signNow sends a notification email (to all recipients at once or in a specific order) with a link to the document(s) to be signed → Recipients sign the document → signNow notifies the sender that the invite is complete via email with the link to signed copies.

A signNow account is needed to create and send invites, recipients don’t need it.

Send Freeform and Role-based invites

Freeform invite - recipients add their signature anywhere on the document.

Role-based invite - document contains fields and has to be filled out and signed in a specific order.

1. Set up access to signNow API from your application.

Install the libraries to access signNow API from your application. In your Sandbox account you’ll find the Basic token for the test app.

# Install the PHP library via Composer

composer require signnow/api-php-sdk

# Or download the source directly: https://github.com/signnow/SignNowPHPSDK

2. Get Bearer token

Get Basic Authorization Token from the API Dashboard and request the Bearer token.

Create a template

Template - an entity that holds the structure of a document and serves for generating its copies.

To create a template:

▶ Set up access to signNow API
▶ Upload a document to signNow
▶ Copy the document ID from the response
▶ Convert the document into a template

1. Set up access to signNow API from your application.

Install the libraries to access signNow API from your application. In your Sandbox account you’ll find the Basic token for the test app.

# Install the PHP library via Composer

composer require signnow/api-php-sdk

# Or download the source directly: https://github.com/signnow/SignNowPHPSDK

2. Get Bearer token

Get Basic Authorization Token from the API Dashboard and request the Bearer token.

Create a document from template

Get document ID and create a document copy out of the template.

In this case document ID equals template ID. For new templates - get it via a POST /template request, for existing templates - from GET /user/documentsv2 or GET /user/documents among the documents where template: true.

curl -X POST \
	https://api-eval.signnow.com/template/{{template_id}}/copy \
	-H 'Authorization: Bearer {{access_token}}' \
	-H 'Content-Type: application/json' \
	-d '{"document_name":"doc_from_template"}'

Signature invites for templates

Steps

Create a document from template In templates for multiple signers, add fillable fields.
Send the invite for the document created

For multiple templates, create a document group first, and then send the invite.

curl -X POST \
  https://api-eval.signnow.com/document/{{document_id}}/invite \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": [
    {
      "email": "signer.email@gmail.com",
      "role_id": "",
      "role": "Signer1",
      "order": 1
    }
  ],
  "from": "sender@gmail.com",
  "cc": [],
  "subject": "Signature Request",
  "message": "Email body for the signature request"
}'

Authentication

The signNow API relies on OAuth 2.0 protocol for authorization. During the authorization flow every user should obtain a token for each application. The Basic Authorization token is generated automatically for the Test app in your account and every other app you create. It’s available in your Sandbox account on the API Dashboard.

In order to request a Bearer token, users should make a call to POST /oauth2/token.

All requests must include an access token in the Authorization Header. POST requests for creating a user or requesting an access token must include the client credentials and a Basic Authorization token.

curl -X POST 'https://api-eval.signnow.com/oauth2/token' \
-H 'Authorization: Basic {{basic_token}}' \
-H 'Content-Type: multipart/form-data;' \
-F 'grant_type=authorization_code' \
-F 'scope=*' \
-F 'code={{authorization_code}}'

Grant type password can be used by API application owners to obtain access tokens for their accounts. To get access to resources of other signNow accounts, use grant type authorization_code.

To get a token with the authorization_code grant type, you have to:

Obtain an authorization code
Request a bearer token using the authorization code

signNow generates an authorization code automatically for the application’s client ID. Having generated the code, signNow passes it as a query parameter of the redirect_URI.

Steps

▶ Embed the following link to signNow Auth page with specific query parameters into your app/crm/website

Required query parameters: client_id, redirect_uri, response_type=code

Link to embed:

Sandbox: https://app-eval.signnow.com/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={YOUR_REDIRECT_URI}

Prod: https://app.signnow.com/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={YOUR_REDIRECT_URI}

Example: link to get the authorization code

https://app-eval.signnow.com/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri=http://your.redirect.uri

▶ Follow the link
▶ Log in to signNow (thus authorizing your app at signNow)
▶ Click Grant access to signNow
▶ The redirect_uri opens. This time with an authorization code in the code query parameter: retrieve authorization code from the URI

Example: redirect URI with an authorization code

http://your.redirect.uri?code={CODE}

▶ Use the authorization code to get a bearer access token with grant type authorization_code

Getting Bearer token with grant type `authorization_code`

curl -X POST 'https://api-eval.signnow.com/oauth2/token' \
-H 'Authorization: Basic {{basic_token}}' \
-H 'Content-Type: multipart/form-data;' \
-F 'grant_type=authorization_code' \
-F 'scope=*' \
-F 'code={{authorization_code}}'

signNow supports several grant types: authorization_code, refresh_token and password.

curl -X POST \
  https://api-eval.signnow.com/oauth2/token \
  -H 'Authorization: Basic {{encoded_client_credentials}}' \
  -H 'content-type: multipart/form-data;' \
  -F 'grant_type=authorization_code' \
  -F 'code={{authorization_code}}'

# Request access token

$entityManager->create(new TokenRequestPassword($username, $password));

# Verify access token

$entityManager->get(Token::class);

# Refresh access token

$entityManager->create(new TokenRequestRefresh($refresh_token));

Field

Fields - spaces in the document designated for signing and editing (filling in) by the recipient. There are different types of fields for different kinds of input: Signature Field, Text Field, Date Field, Formula Field etc.

Field object in signNow

Every field is an object that contains field properties: ID, role, label, name etc.

Field properties: field ID, its type, the role it’s been assigned to, x/y coordinates in the document, field width and height, its label, prefilled text, and the custom defined option.

Field properties are described in a fields array.

Content of a field can be found in texts, signatures, or checks arrays (“checks” for checkboxes) based on the type of data that’s been filled in. You can retrieve all the values from Text, Dropdown, Calculated, Hyperlink, or Date fields from the texts array.

Each field has its own ID. You can find it as element_id parameter in the fields array.

When the field is completed, it appears in the texts array with an id parameter equal to element_id from the field array.

Add fillable fields

Steps:

▶ Get document ID

▶ Add fillable fields:

specify the position on the page
width and height
page number
field label
role
type
whether it’s required or not
prefilled text if any

Required parameters for a fillable field object:

⬥ “x” - horizontal position on the page; how many pixels away from the left edge of the page

⬥ “y” - vertical position on the page; how many pixels away from the top of the page

⬥ “width” - how many pixels wide the field is

⬥ “height” - how many pixels high the field is

Hint

Equivalent A4 paper dimensions in pixels at 300 dpi or 72 dpi resolution respectively are: 2480 ⨯ 3508 pixels and 595 ⨯ 842 pixels.

⬥ “page_number” - page numbering starts with 0

⬥ “label” - hint for the signer inside a fillable field about the field type, e.g. first_name or text_1; once the field is filled in, the value automatically appears in all the fields with the same label

⬥ “name” - unique field name

⬥ “role” - which role the field is assigned to, e.g. Signer_1

⬥ “required” - whether the field is mandatory to fill in, e.g. true/false

⬥ “type” - could be “text”, “signature”, “initials”, “checkbox”, “radiobutton”, or “enumeration” (stands for a dropdown menu)

⬥ “prefilled_text” - editable text that appears in the field when the signer opens the document, e.g. Lucy

curl -X PUT \
  https://api-eval.signnow.com/document/{{document_id}} \
  -H 'Authorization: Bearer {{access_token}}'\
  -H 'Content-Type: application/json' \
  -d '{
  "fields": [
	{
    "x": 305,
    "y": 18,
    "width": 122,      
    "height": 10,
    "page_number": 0,
    "label": "first_name",
    "role": "Signer",
    "required": true,
    "type": "text",
    "prefilled_text":"John"
  },
  {
    "x": 305,
    "y": 38,
    "width": 122,      
    "height": 10,
    "page_number": 0,
    "label": "last_name",
    "role": "Signer",
    "required": true,
    "type": "text",
    "prefilled_text":"Doe"
  },
  {
    "x":305,
    "y":67,
    "width":100,
    "height":34,
    "page_number":0,
    "label":"a sample label",
    "role":"Signer",
    "required":true,
    "type":"signature"
  }
]
}'

Signature and Initials fields

Signature field - a type of field which can hold a signature (be signed).

Initials field - also a type of field which can hold a signature (be signed). It differs from a Signature field because it’s not legally binding. To add their Initials, Signers use the same instruments in signNow editor that they do to put a signature - draw, type, or upload.

There are two ways to add a Signature to a document: add a Signature field directly by making a PUT .../document/{document_id} request (case 1); or create a freeform invite - the signature field shows up only when the recipient opens the document (case 2).

Case 1 is described in this article. To add a Signature field, document owners should open fields array in the request body, add a field and specify its "type" parameter as "signature".

Case 2 is a part of the flow when the document owner (API user) creates a freeform invite for a document with no fields.

When the freeform invite has been created, API users get two arrays in the response: "signatures", which is empty, and "requests", which contains the details of the freeform invite.

Here’s a response example when a Signature field has been added to the document*.

*In this example we show the response to a GET .../document/{document_id} request. The response to a PUT .../document/{document_id} is only a document ID, e.g. "id": "3db38d8c1fdfca762b25d57d82b3cf327a65485e".

Response when a Signature field has been added to a document

{
  "signatures": [],
  "requests": [
    {
      "unique_id": "827a6dc8a83805f5969883304d2166b75ba19cf3",
      "id": "827a6dc8a83805f5969883304d2166b75ba19cf3",
      "user_id": "40204b3344984768bb16d61f8550f8b5edfd719a",
      "created": "1579090178",
      "originator_email": "document_owner@signnow.com",
      "signer_email": "signer1@gmail.com",
      "canceled": null,
      "redirect_uri": null
    }
  ]
}

In this example we use a document with no other fields or elements. Here, the "unique_id" and the "id" parameters stand for the object ID of the signature invite we’ve just created.

When the recipient signs this invite, the API user, a.k.a. the document owner, receives a new response. This time the "signatures" array contains a signature object and the "requests" array has the "signature_id" of the signature object.

Response when the Signer has signed and submitted the document

{
  "signatures": [
    {
      "id": "5cbcf9d0e5b0e77b78fef3202000220f01fea3cf",
      "user_id": "fdbf8063a803daa7ec0d0f6476e78c4aa445a86f",
      "signature_request_id": "827a6dc8a83805f5969883304d2166b75ba19cf3",
      "email": "signer1@gmail.com",
      "page_number": "0",
      "width": "141",
      "height": "42",
      "x": "372",
      "y": "448",
      "created": "1580125749",
      "data": "iVBORw0KGgoAAAANSUhEUg=="
    }
  ],
  "requests": [
    {
      "unique_id": "827a6dc8a83805f5969883304d2166b75ba19cf3",
      "id": "827a6dc8a83805f5969883304d2166b75ba19cf3",
      "user_id": "40204b3344984768bb16d61f8550f8b5edfd719a",
      "created": "1579090178",
      "originator_email": "document_owner@signnow.com",
      "signer_email": "signer1@gmail.com",
      "canceled": null,
      "redirect_uri": null,
      "signature_id": "5cbcf9d0e5b0e77b78fef3202000220f01fea3cf"
    }
  ]
}

Here is an example of

the request body when adding a Signature and an Initials field to a document;
the response when Signature and Initials fields have been successfully added (from GET .../document/{document_id});
the response when Signer has signed and filled in the Signature and Initials fields

Example with a Signature and an Initials field

{
  "fields": [
    {
      "page_number": 0,
      "type": "signature",
      "name": "SignatureName",
      "role": "Signer 1",
      "required": true,
      "height": 40,
      "width": 50,
      "x": 217,
      "y": 32
    },
    {
      "page_number": 0,
      "type": "initials",
      "name": "InitialsName",
      "role": "Signer 1",
      "label": "InitialsLabel",
      "required": true,
      "height": 52,
      "width": 33,
      "x": 300,
      "y": 443
    }
  ]
}

Checkbox fields

Checkbox - a field that can be checked by a checkmark.

When the document owners create a Checkbox field, they may keep it empty, or check it. The state of the Checkbox is defined in the prefilled_text parameter.

Here’s an example of the JSON request body when adding a Checkbox field to a document via API.

{
  "client_timestamp": 1527859375,
  "fields": [
    {
      "page_number": 0,
      "type": "checkbox",
      "name": "CheckboxName",
      "role": "Signer 1",
      "prefilled_text": true,
      "label": "checkboxLabel",
      "required": true,
      "height": 15,
      "width": 11,
      "x": 70,
      "y": 270
    }
  ]
}

In Checkbox fields, prefilled_text parameter accepts boolean values when adding a field to a document. However, when the recipient checks/unchecks the field, prefilled_text contains a string value in JSON document response. This string stands for a boolean.

Parameter	Value
`prefilled_text=="1"`	(boolean) the field is checked
`prefilled_text==""`	(boolean) the field is not checked

Here’s a response example when the Checkbox field has been checked and the Signer submitted the document.

{
  "checks": [],
  "fields": [
    {
      "id": "72aec107797a499c8e85d08f08572ccd86668e60",
      "type": "checkbox",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 70,
        "y": 270,
        "width": 11,
        "height": 15,
        "required": true,
        "name": "CheckboxName",
        "prefilled_text": "1"
      },
      "role": "Signer 1",
      "originator": "document.owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "aa64e927972b48858f6090f40c1b4a7b589835e0",
      "element_id": null,
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "aa64e927972b48858f6090f40c1b4a7b589835e0"
    }
  ]
}

Dropdown fields (Enumeration)

Dropdown - a field with a number of preset options to fill in. Signer can either select one of the options available or type in a different option.

Dropdown fields can be editable (preset options + add your own option) or non-editable (preset options only).

This type of field in signNow is called enumeration.

Adding Dropdown fields to a document

To add a Dropdown field, document owners should open fields array in the request body, add a field and specify its "type" parameter as "enumeration".

Then, to add options, they should open another array called "enumeration_options" within the "fields" array. `

Dropdown field (Enumeration) example

"fields":[
{
            "page_number": 0,
            "type": "enumeration",
            "name": "EnumerationName",
            "role": "Signer 1",
            "prefilled_text": 123,
            "label": "EnumerationLabel",
            "required": true,
            "custom_defined_option": false,
            "enumeration_options": [
                "123",
                "43",
                "12345"
            ],
            "height": 40,
            "width": 50,
            "x": 100,
            "y": 32
}
]

Dropdown field parameters

Parameter	Meaning
`json_attributes.prefilled_text`	Here you enumerate dropdown options which Signer sees when opens a document
`json_attributes.custom_defined_options`	`false` - allows Signer to select only from the enumeration options `true` - allows Signer to select an enumeration option or add their own option

Custom_defined_options is a boolean

When you add custom_defined_options parameter to the dropdown field, remember, it requires a true/false response. To set the true/false options, use these values:

“1” - true
“” - false

Reading Dropdown fields in responses

In a response before sending a document to the recipient
e.g. from GET /document/{{document_id}}

{
  "enumeration_options": [ // list of all the dropdown options
    {
      "id": "61ccd5a0359c4656acfa8f2af315397117c093a9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "123", // value that Signers see as a dropdown option 
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "32be55abedef4fbda41f44c24adc356408e5dde9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "43",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "498c734dcc6d4ce7946edec3b5dc68303766918b",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "12345",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    }
  ],
  "fields": [
    {
      "id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "type": "enumeration",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 100,
        "y": 32,
        "width": 50,
        "height": 40,
        "required": true,
        "name": "EnumerationName",
        "label": "EnumerationLabel",
        "prefilled_text": "123",
        "custom_defined_option": ""
      },
      "role": "Signer 1",
      "originator": "document.owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a",
      "element_id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a"
    }
  ]
}

In a response when the recipient selected the option in the Dropdown field

You can find the selected option in the texts array of the response. Its id parameter will be equal to the element_id parameter of the completed field in the fields array.

In the following example, Signer:

opened the document,
saw the Dropdown field with default value prefilled_text="123",
clicked on the Dropdown field,
selected the "12345" value,
saved the document.

{
  "enumeration_options": [ // list of all dropdown elements
    {
      "id": "61ccd5a0359c4656acfa8f2af315397117c093a9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "123", // value of a dropdown option 
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "32be55abedef4fbda41f44c24adc356408e5dde9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "43",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "498c734dcc6d4ce7946edec3b5dc68303766918b",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "12345",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    }
  ],
  "fields": [
    {
      "id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "type": "enumeration",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 100,
        "y": 32,
        "width": 50,
        "height": 40,
        "required": true,
        "name": "EnumerationName",
        "label": "EnumerationLabel",
        "prefilled_text": "123", // default value of the dropdown field
        "custom_defined_option": ""
      },
      "role": "Signer 1",
      "originator": "document.owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a",
      "element_id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a"
    }
  ],
  "texts": [
    {
      "id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "user_id": "a954c1e8a45ff6bb0d233d8ac160bd4e3271ca94",
      "page_number": "0",
      "email": "signer1@gmail.com",
      "font": "Arial",
      "size": "10",
      "data": "12345", // the dropdown option selected by Signer
      "data_encrypted": null,
      "x": "298",
      "y": "278",
      "line_height": "12.00",
      "created": "1581419109"
    }
  ]
}

As a result of Signer’s actions, signNow created an element that contains Signer’s selection in the texts array. You can find it using field[].element_id in the texts array where texts[0].id == fields[0].id.

If the document owner didn’t make the Dropdown field required, and the Signer didn’t select any option in this field, the element in texts won’t be created. It means that the Dropdown field element hasn’t received any value from the Signer.

How to fill in Dropdown fields using API

To fill in the Dropdown field, make a PUT /document/{{document_id}} request. Enter the value as "data" parameter in the texts array.

curl -X PUT \
  https://api-eval.signnow.com/document/{{document_id}} \
  -H 'Authorization: Bearer {{access_token}}’\
  -H 'Content-Type: application/json' \
  -d '{
  "fields": [
{
    "x": 305,
    "y": 278,
    "width": 122,      
    "height": 20,
    "page_number": 0,
    "label": "select_dropdown",
    "role": "Signer",
    "required": true,
    "type": "enumeration",
    "prefilled_text":"123"
  },
{ 
  "texts": [
  {
      "page_number": 0,
      "field_id": "{{field_id_EnumerationName}}", // Selected value to put into the Dropdown
      "data":"12345", // Selected value to put into the Dropdown
      "client_timestamp": {{$timestamp}}, // UNIX timestamp, optional
      "x": 298,
      "y": 278,
      "font": "Arial",
      "line_height": 12,
      "size": 10
   }]
}

Attachment fields

Attachment field - a type of field that contains an attached file.

To add an Attachment field to a document, make a PUT /document/.../{document_id} request, open fields array in the request body, add a field and specify its "type" parameter as "attachment".

Request body to add an Attachment field

{
  "fields": [
    {
      "page_number": 0,
      "type": "attachment",
      "name": "AttachmentName",
      "role": "Signer 1",
      "label": "AttachmentLabel",
      "required": true,
      "height": 40,
      "width": 35,
      "x": 70,
      "y": 350
    }
  ]
}

Here’s a response example when an Attachment field has been added to the document*.

{
  "attachments": [],
  "fields": [
    {
      "id": "98e9a9e470834b16a81d51f7d260849dea79b789",
      "type": "attachment",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 70,
        "y": 350,
        "width": 35,
        "height": 40,
        "required": true,
        "name": "AttachmentName",
        "label": "AttachmentLabel"
      },
      "role": "Signer 1",
      "originator": "document_owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "783262096c88498c9b118a8fe860761eb10986e4",
      "element_id": null,
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "783262096c88498c9b118a8fe860761eb10986e4"
    }
  ]
}

The Signer gets the opportunity to upload files and attach them to the field. In a JSON response when the files have been attached, the API user gets the attachment ID which can later be used to download the attachments.

The attachment ID value is stored in the "id" parameter of the "attachments" array and the "element_id" parameter of the "fields" array.

{
  "attachments": [
    {
      "id": "31581a46edf1c1a160d125f2f501a9bfb7970323",  // equals the "element_id" in the "fields" array
      "user_id": "a954c1e8a45ff6bb0d233d8ac160bd4e3271ca94",
      "page_number": "0",
      "width": "131",
      "height": "22",
      "x": "639",
      "y": "388",
      "line_height": "145.00",
      "created": "1581419101",
      "original_attachment_name": "repository-open-graph-template.png",
      "filename": "40a594f2c3e4dd09735ed2f46fdbe7f6d2c39eaf.png",
      "file_type": "0",
      "mime_type": "png",
      "file_size": "51470",
      "json_attributes": {
        "scan_determination": "Unsupported file format"
      }
    }
  ],
  "fields": [
    {
      "id": "98e9a9e470834b16a81d51f7d260849dea79b789",
      "type": "attachment",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 70,
        "y": 350,
        "width": 35,
        "height": 40,
        "required": true,
        "name": "AttachmentName",
        "label": "AttachmentLabel"
      },
      "role": "Signer 1",
      "originator": "document_owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "783262096c88498c9b118a8fe860761eb10986e4",
      "element_id": "31581a46edf1c1a160d125f2f501a9bfb7970323",  // contains the attachment.id
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "783262096c88498c9b118a8fe860761eb10986e4"
    }
  ]
}

Hyperlink fields

Hyperlink field - a type of field which contains a URL.

To add a Hyperlink field to a document, make a PUT /document/.../{document_id} request, open fields array in the request body, add a field and specify its "type" parameter as "hyperlink".

{
  "fields": [
    {
      "page_number": 0,
      "type": "hyperlink",
      "name": "HyperlinkName",
      "role": "Signer 1",
      "label": "HyperlinkLabel",
      "required": true,
      "link": "<http://signnow.com>",
      "hint": "signnow.com",
      "height": 35,
      "width": 31,
      "x": 10,
      "y": 10
    }
  ]
}

Here’s a response example when a Hyperlink field has been added to the document*.

{
  "hyperlinks": [],
  "fields": [
    {
      "id": "ccbd8ecde5074f2a9669ceed2c4aad6d9296af07",
      "type": "hyperlink",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 10,
        "y": 10,
        "width": 31,
        "height": 35,
        "required": true,
        "name": "HyperlinkName",
        "label": "HyperlinkLabel",
        "link": "http://signnow.com",
        "hint": "signnow.com"
      },
      "role": "Signer 1",
      "originator": "document_owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "3bb1bbf2607f489299f1c57b1ffd29509809d831",
      "element_id": null,
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "3bb1bbf2607f489299f1c57b1ffd29509809d831"
    }
  ]
}

When a Signer fills in the Hyperlink field and submits the document, the response contains the "hyperlinks" array where you can find the URL as the "data" parameter value.

{
  "hyperlinks": [
    {
      "id": "68803ee370e54ad4b322414d9eca5a9d37e30a91",
      "user_id": "a954c1e8a45ff6bb0d233d8ac160bd4e3271ca94",
      "page_number": "0",
      "email": "signer1@gmail.com",
      "font": "Arial",
      "size": "8",
      "data": "http://signnow.com",
      "label": "HyperlinkLabel",
      "x": "234",
      "y": "15",
      "line_height": "9.00",
      "created": "1581419110"
    }
  ],
  "fields": [
    {
      "id": "ccbd8ecde5074f2a9669ceed2c4aad6d9296af07",
      "type": "hyperlink",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 10,
        "y": 10,
        "width": 31,
        "height": 35,
        "required": true,
        "name": "HyperlinkName",
        "label": "HyperlinkLabel",
        "link": "http://signnow.com",
        "hint": "signnow.com"
      },
      "role": "Signer 1",
      "originator": "document_owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "3bb1bbf2607f489299f1c57b1ffd29509809d831",
      "element_id": "68803ee370e54ad4b322414d9eca5a9d37e30a91",
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "3bb1bbf2607f489299f1c57b1ffd29509809d831"
    }
  ]
}

Conditional Fields

Conditional Fields allow you to manage sets of dependencies between fields. When a field is “dependent” (conditional), it will only be available for editing and displayed if the state of the “dependee” field matches the right condition.

The easiest way to create сonditional fields is to use the signNow web app (open the document in your signNow account):

Create conditional fields via the web application (signNow editor)
Find the field description in the "fields" array in the response from GET /document

Web app instructions: Conditional field settings in the Invite to Sign document (1 Signer)

A. How to apply the Conditional setting to a field:

Start by adding at least 2 fillable fields. The Conditional field setting works with all fillable fields available in the Tools bar.
Open the field settings by clicking on the field that you want to have the ‘Conditional’ logic.
Expand the Advanced options tab.
Check the Make this field conditional checkbox. The condition settings will appear.
Set the condition under which the field will be shown.

5.1 Select the field you want to make a dependency with (Required action). In the first dropdown list all unique field names in the document are shown.

Select the field name from the list to build a dependency. That chosen field then becomes the selected option to build a dependency with.

Scroll to the last option Choose by clicking in the list and select it. Then click on any field in the document. The chosen field then becomes the selected option to build a dependency with.

5.2 Select a dependency rule from the second dropdown list (Required action).

Here are available Dependency Rules:

Signature: is signed/is not signed
Text field: is filled in/is not filled in
Date: is filled in/is not filled in
Initials: is initialed/is not initialed
Checkbox: is checked/is not checked
Radiobutton: is/is not → any value/one of values from the radio group
Dropdown: is/is not → any value/one of values from the dropdown
Attachment: is uploaded/is not uploaded
Calculated field: is filled in/is not filled in

5.3. Set the ‘1st level’ for Multiple conditions, if conditional logic requires more than 1 rule to function (Optional action)

Select the rule for the multiple conditions options:
- Any of the following (means that at least one condition in the list must be true)
- All of the following (means that all conditions in the range must be true)
- None of the following (means that all conditions in the list must be false)
- Not all of the following (means that all conditions in the range must be true)
- Click on the ‘plus’ button under the first condition

5.4 Set the ‘2d level’ for Multiple conditions, if conditional logic require more than 1 rule under one specific condition (Optional Action)

Click on the ‘arrow down’ button in the specific condition block
Set the rules for the condition according to paragraph 5. It’s impossible to make both fields interdependent on each other (cyclic bilateral dependence). This means, once a dependency from the ‘field A’ to the ‘field B’ is applied, then for the ‘field B’ there will be no ‘field A’ option as described in paragraph 5.1.

Save the field settings by clicking on the ‘OK’ button.
The document can be sent via the ‘Invited to Sign’ option on the general invite rules. When previewing the document with Conditional field via the ‘Invite’ section, all fields are visible.
When trying to delete a field, which is part of the existing Conditional logic, a modal window appears with the following message: ‘Cannot remove field. This field is referenced as a dependency of another field. Please remove all conditional references to other fields and try again.’ By clicking on the ‘Ok’ button or the cross icon, the modal is closed and the delete action is canceled.

To remove the whole Conditional setting from the field, uncheck the Make this field conditional checkbox in the Advanced options from the field settings and then click OK in the confirmation modal.

B. How to sign a document with Conditional logic?

When signer receives a document to sign, that contains at least 1 conditional field, the field will be invisible until the set condition is met.
As soon as the conditional rule for this field is met (rules set by the Sender in paragraph A-5), the field becomes visible and can be filled in by the Signer.
If an action is made by the Signer that triggers the conditional rule to be ‘false’, the field becomes invisible and all filled-in content is deleted. When that field is later changed and the conditional rule becomes ‘true’, the field is visible again, but is empty by default.
Prefilled values of fields taking part in the Conditional field logic are considered as valid inputs and thus affect the Conditional field’s visibility. The Signer can edit the prefilled values to custom ones.
Navigating using the ‘Tab’ key or using the page Markes, doesn’t skips through the invisible conditional fields.
All general fillable field rules are applied to Conditional fields when they’re visible.

Web app instructions: Conditional field settings in the Invite to Sign document (2 Signers)

Add at least 2 fillable fields and assign them to 2 Signers. Conditional settings work with all fillable fields available in the Tools bar.
Open the field settings by clicking on the field that you want to have the ‘Conditional’ logic.
Expand the Advanced options tab.
Check the Make this field conditional checkbox. The condition settings will appear.
Modal appears with the following info: to make this field dependent on a field with a different role, a few things will happen:

Editing the signing order becomes unavailable.
Adding this document to a document group becomes unavailable.
These restrictions can be removed by removing all conditions that span multiple signers.

By clicking the OK button the Condition setting is available.

Condition settings can be made according to the rules from paragraph A-5
Fields on Step 1 of either of the Signers can’t be conditionally made dependant on each other, thus they’re not available to apply conditions to. Only other non Step 1 fields can be made conditionally dependant for another Signer.
Set the condition under which the field will be shown.
When trying to change the Signing role of the field according to general rules, the warning modal appears and changes won’t be applied. To change the Signing role of the field, which is referenced as a dependency of another field, first you need to remove all conditional references to other fields and then try again.
It’s impossible to change the Signer role of the field, which is under the Conditional logic. When attempting to do this change, a warning modal appears, saying that this field is referenced as a dependency of another field, you need to remove all conditional references to other fields and then try again.

Example: Invite to Sign (1 Signer)

In this example, Signature field is conditional. It depends on the Text field labeled “Last name”. The condition is: if “Last name” is filled in, then show the Signature field.

Example: Invite to Sign (2 Signers)

In this example, two fields are conditional: “Signer 2 Last Name” (Text field) and “Signature Signer 2” (Signature field). Both fields are assigned the Signer 2 role. They depend on the fields assigned the Signer 1 role. The condition is: if “Signer 1 Last Name” (Text field) and “Signature Signer 1” (Signature field) are filled in and signed, then show “Signer 2 Last Name” and “Signature Signer 2”.

Cross-Role Conditional Fields

When you choose to make this a dependent on a field in a different role, a few things will happen:

You can no longer edit the signing order.
You cannot add this document to a document group.
You can remove these restrictions by removing all conditions that span multiple signers.

Operators for Conditions

Operator	Meaning	Example
Any of the following	means that at least one condition in the list must be true	`"operator": "or",`
All of the following	means that all conditions in the range must be true	`"operator": "and"`
None of the following	means that all conditions in the list must be false	`"operator": "not"` in the overall dependency + `"operator": "or",` in the parent field dependencies
Not all of the following	means that all conditions in the range must be true	`"operator": "not"` in the overall dependency + `"operator": "or",` in the parent field dependencies

Calculated Fields

Calculated Field is a numeric field that derives its data from the calculation of other fields.

The easiest way to create calculated fields is to use the signNow web app (open the document in your signNow account):

Create calculated fields via the web application (signNow editor)
Find the field description in the "fields" array in the response from GET /document

Web app instructions: Calculated fields in the Invite to Sign document (1 Signer)

A. How to create a Calculated Field:

To create a Calculated field, add the Calculated Field fillable field to the document (just like any other fillable field).
Specify the calculation formula. The calculation formula can use the following:
2.1 Positive numbers: In case of using negative numbers, the formula is saved in the Editor’s mode, but in the Signing mode that Calculated field becomes a Text field.
2.2 Text fields: should have a number type validation (marked with the symbol) to be able to use them in a Calculation formula. If there’s a different validation method applied, the field isn’t shown in the list of possible operands for the Calculation formula.
2.3 Dropdown field: should have only numbers in options to be available for choosing in a Calculation formula. If there is at least 1 letter in the dropdown options, the field won’t be seen in the list of possible options for the Calculation formula.
2.4 Other existing Calculated fields

A Calculated Field modal window is shown.
This field is required by default. Uncheck the Required checkbox to instead make this field optional.

Enter a formula in the Formula dialog box.
3.1 Select the operand or enter a numeric value. The formula may contain unique field names and numbers. Add curly brackets to enter the unique name of the fields, then add numbers without brackets. Formulas can be calculated via addition, subtraction, multiplication and division. You can also round the value of the field to a specific amount of decimal places.
3.2 Operands can be grouped using round brackets.

3.3 Select an operator (+ - / *) and place them between the operands.
3.4 The formula will pass validation when there are at least 2 operands in the formula. Otherwise an error Operand is missing is shown.
3.5 The formula will pass validation when there is at least 1 operator in the formula. Otherwise an error Formula must have at least one operator is shown.
Select the number of decimal places. 2 is set by default. The min. value is 0. The max. value is unlimited. This field can’t be left empty.

When the formula passes validation, the Create button is enabled. By clicking on it the modal is closed and the field is in focus.

The calculated field has additional basic setting as any typical fillable field: Label, Role assigning, Advanced settings. The current formula is also seen in the field settings.

An automatically generated Unique Field name for the Calculated field starts with Formula_ prefix and finishes with the number of all current Calculated fields in the document.

When trying to delete the field, which is used as an operand in a Calculation formula in an existing field within the document, a confirmation modal Cannot remove field. This field is used in some formulas and can’t be deleted. Please edit formulas. will appear. By clicking on the Ok button or the cross icon the modal is closed and the field is not deleted. The field can be deleted only after it’s removed from all existing Calculation formulas.

B. How to sign documents with a Calculated field formula?

The Calculated field is shown as filled (green) with a number in the input corresponding to the results of the formula in its current state (with the number of decimals that was set by the Sender in paragraph A6).
The prefilled value of the fields which take part in a Calculation formula is considered as an input and is counted in the formula. Signers can change the prefilled value.
When fields which take part in a Calculation formula are filled according to validation rules and if these fields aren’t in focus, then the input in a Calculated field is automatically changed to the result of the Calculation formula.
It’s impossible to change the input in a Calculated field manually. Changing the input is possible only if changing the value of the fields which take part in the Calculation formula. Changes will apply after these fields aren’t in focus.
If the amount of numbers in a Calculated field exceeds 19, the input of the field changes to ‘#can’t calculate’

Web app instructions: Calculated fields in the Invite to Sign document (2 Signers)

C. How to create a Calculated field?

It’s possible to assign fields, which takes part in the Calculation formula to different signers.
For 2 or more signers with assigned fields, all fields which pass validation, as described in paragraph A2, can be used as operands in the Calculation formula in the same way, as for 1 signer (see paragraphs A2-A4).
There are no restrictions in choosing operands from different signers (signing order is not taken into account).
When trying to delete a signer, a modal Are you sure you want to continue? Saving these changes will remove the fields for Signer is shown and additionally a Calculate field error modal appears Cannot remove field. This field is used in some formulas and can’t be deleted. Please edit formulas. After closing the modals, a Calculated field assigned to this Signer is deleted. All the other fields remain in the document with an empty Role.
When adding a new signer, after clicking on the OK button the Calculated field error modal appears Cannot remove field This field is used in some formulas and can’t be deleted. Please edit formulas.. A signer is added.

D. How to sign a document with a Calculated field formula?

In case when a Calculation formula uses operands from each signer separately (formula doesn’t use operators from different signers), then the process described in paragraph B is applied.
In case when a Calculation formula uses operands from different signers the following is applied:
**2.1 For Signer 1: **

If a Calculated field is assigned to Signer 2 (or other signers), but the formula is a result of Signer 1 inputs, then Signer 1 sees the field as a filled field with ‘0.00’ input value and is unchangeable.
If a Calculated field is assigned to Signer2 (or other signers), but the formula is partially dependant on Signer 1 inputs, then Signer 1 sees the field and only the calculation results of his inputs are shown.
If a Calculated field is assigned to Signer 1, but the formula is a result of Signer 2 (or other signers) inputs, then Signer 1 doesn’t see the Calculated field.
2.2 For Signer 2 (or other signers):
If a Calculated field is a result of Signer 1 inputs, then the result is shown.
If a Calculated field is partially dependant on Signer 1 inputs, then when Signer 2 (or other signers) enters his input the result is shown.
If a Calculated field is assigned to Signer 1, but is a result of Signer 2 (or other signers) inputs, Signer 2 can see input in the Calculated field as ‘0.00’ displayed in the document. Signer 2 won’t be able to save the document, as an error There was a problem signing the document will appear and The document is incomplete. will be shown.
If a Calculated field is assigned to Signer 1, but the formula is a result of Signer 2 (or other signers) inputs, then Signer 2 can see the result displayed in the document.

Operators in Calculated fields

Operation	Symbol in Web app	Operator
Addition	+	`"operator": "add",`
Subtraction	-	`"operator": "sub"`
Multiplication	*	`"operator": "mul"`
Division	/	`"operator": "div"`

Example: Calculated fields

In this example, the Calculated field is set to add the values of Signer 1 Order Amount and Signer 2 Order Amount fields.

Text Tags

Text Tags - specific combinations of symbols and letters in a document that represent fillable fields.

Text Tags are always typed in the document first. Some of them require additional information in the body of API requests. After the document with Text Tags is uploaded to SignNow, Text Tags convert to fillable fields. Requests containing Text Tags have to be directed to the POST /document/fieldexract.

signNow supports three kinds of Text Tags: Simple Text Tags, Complex Text Tags, and Invite Text Tags.

Simple Text Tags

Simple Text Tags are added to the document only. You don’t have to specify any field properties in an API request. Upload the document using POST /document/fieldextract, add only the name of the document in the request:

curl -X POST \
  https://api-eval.signnow.com/document/fieldextract \
  -H 'Authorization: Bearer {{access_token}}' \
  -F 'file=@/path/to/FILE_NAME.pdf'

When you add a Simple Text Tag to a document, you should combine keys in curly braces in a specific order. Every key stands for the property of a field.

Table 1. The Order of Field Properties in a Text Tag

KEY	What does it mean?	Accepted format and values	When do fields require this key?
`t`	TYPE of the field	`s` (for signature), `i` (for initials), `t` (for text), `d` (for dropdown), `c` (for checkboxes), `f` (for files), `rn` (radio name for radio buttons)	Specify it for every field
`r`	REQUIRED	`y` (for required), `n` (for optional)	Specify it for every field
`o`	ROLE	`"Signer 1"`	Specify it for every field
`l`	LABEL	`label 1`	Only for Text, Dropdown, and Attachment fields
`dd`	DROPDOWN	`"option1, option2, option3, ...."`	Only for Text and Dropdown fields
`f`	FILE	`"doc1.pdf"`	Specify for file attachments
`w`	WIDTH	`"w: <num>"`	Specify it for every field
`h`	HEIGHT	`"h: <num>"`	Specify it for every field
`v`	VALIDATOR_ID	`"v:<id>"`	Only for Text Field
`lsd`	LOCK_SIGNING_DATE	`"y"` (for yes, set the the current date when signing), `"n"` (for no Date set by default)	Only for Date Field

Simple Text Tag formula looks like this:

"{{t:[s/i/t/d/c];r:[y/n];o:"Role";l:"date";w:width;l:length;v:"validator_id";}}

Table 2. Simple Text Tag Examples

Task	Simple Text Tag
Create a required signature field for the role ‘CEO’: width ‘100’, and height ‘15’	{{t:s;r:y;o:“CEO”;w:100;h:15;}}
Validate a US phone number in an optional text field for the role ‘CFO’, label ‘phone’, width ‘100’, height ‘15’, and validator_ID ‘13cc1d661da456d27b249b73056ed4d1f2e72d8e’	{{t:t;r:n;o:“CFO”;l:“phone”;w:100;h:15;v:“13cc1d661da456d27b249b73056ed4d1f2e72d8e”;}}
Create a required dropdown field for the role ‘Employee’, labeled ‘Year’, with dropdown options ‘2017, 2018, 2019’	{{t:d;r:y;o:“Employee”;l:“Year”;dd:“2017,2018,2019”;}}
Create a required Attachment field for the role ‘Employee’: width ‘100’, and height ‘15’	{{t:s;r:y;o:“Employee”;f:y;w:100;h:15;}}

Text tags for Radio Buttons

To add a Radio Button, follow this example:

rn - “radio name”, the name of your radio button. Several radio buttons related to one question/section comprise a radio button group. If you’d like to add a radio button group, add several text tags with the same radio name.

rv - radio value. Use this parameter to identify what value can be checked/unchecked by this radio button.

checked - detrmines whether the button is checked by default. Possible values: 0 - unchecked; 1 - checked.

Complex Text Tags

Complex Text Tags are also added to a document first but field properties are then specified in the body of the request.

When you add a Complex Text Tag to a document, you only put a tag name in double curly braces, like so {{tag_name}}.

Then, make a request to POST /document/fieldextract. In your request body, specify parameters of the field you saved place for with your {{tag_name}}.

Parameters for a Complex Text Tag:

⬥ “tag_name” - duplicates the name without curly braces, e.g. tag_name

⬥ “role” - which role the field is assigned to, e.g. Signer_1

⬥ “label” (optional) - hint for the signer inside a fillable field about the field type, e.g. first_name or text_1; once the field is filled in, the value automatically appears in all the fields with the same label

⬥ “required” - whether the field is mandatory to fill in, e.g. true/false

⬥ “type” - could be “text”, “signature”, “initials”, “checkbox”, “attachment”, or “enumeration” (stands for a dropdown menu)

⬥ “prefilled_text” (optional) - editable text that appears in the field when the signer opens the document, e.g. Lucy

⬥ “validator_id” (optional) - data validation format for a field.

Check for available formats in Data Validators.

⬥ “width” - how many pixels wide the field is

⬥ “height” - how many pixels high the field is

Table 3. Complex Text Tag Examples

Tag	Example
Text Tag	{ tag_name:‘employee’, role:‘employee’, label:‘Label1’, required:true, type:‘text’, width:100, height:20 },
Date Validator Tag	{ “tag_name”:“DateValidatorTagExample”, “role”:“Role1”, “label”:“Date of Birth”, “required”:true, “type”:“text”, “height”:15, “width”:100, “lsd”:y, “validator_id”:“13435fa6c2a17f83177fcbb5c4a9376ce85befeb” },
Initials Tag	{ “tag_name”:“InitialsTagExample”, “role”:“CLIENT”, “required”:true, “type”:“initials”, “height”:15, “width”:40 },
Signature Tag	{ “tag_name”:“SignatureTagExample”, “role”:“CLIENT”, “required”:true, “type”:“signature”, “height”:15, “width”:200 },
Dropdown Tag	{ “tag_name”:“DropDownTagExample”, “role”:“Role1”, “label”:“Options”, “required”:true, “type”:“enumeration”, “height”:15, “width”:100, “custom_defined_option”:false, “enumeration_options”:[“All”,“None”] },
Attachment Tag	{ tag_name:‘AttachmentTagExample’, role:‘Role2’, label:‘Label2’, required:true, type:‘attachment’, width:100, height:20 },
Checkbox Tag	{ “tag_name”:“CheckboxTagExample”, “role”:“CLIENT”, “required”:true, “type”:“checkbox”, “height”:12, “width”:12, }
Radiobutton Group Tag	[ { “tag_name”: “radio_group1”, “page_number”: 0, “role”: “Employee”, “label”: null, “required”: true, “x”: 36, “y”: 246, “width”: 340, “height”: 13, “radio”: [ { “page_number”: 0, “x”: 36, “y”: 246, “width”: 13, “height”: 13, “checked”: “0”, “value”: “value-1”, “x-offset”: 0, “y-offset”: 0 }, { “page_number”: 0, “x”: 36, “y”: 246, “width”: 13, “height”: 13, “checked”: “1”, “value”: “value-2”, “x-offset”: 0, “y-offset”: 14 }, { “page_number”: 0, “x”: 36, “y”: 246, “width”: 13, “height”: 13, “checked”: “0”, “value”: “value-3”, “x-offset”: 0, “y-offset”: 28 } ], “name”: “Group_name”, “type”: “radiobutton” } ]

Note: To specify the position of each radio button on the screen you can use the y-offset and x-offset parameters.

Lock signing date option

Remember: you can set the current date when the recipient is signing the document as a Date field value. To use this option in a text tag, add the "lsd" parameter to your Date Validator tag. Possible values: “y” (for yes, set the the current date when signing), “n” (for no Date set by default).

Invite Text Tags

Invite Text Tags are added to the document only, no additional configuration in the request body. Among field properties, you can specify signer’s email address. So, when you upload a document to POST /document/fieldextract, it’s automatically sent for signautre to that address. There’s no need to make a separate request to POST /document/invite.

Table 4. Invite Text Tag Examples

Invite Text Tags
{{t:e;o:“Role1”;e:“siri@mailinator.com”;}} {{t:e;o:“Client”;e:“siri2@mailinator.com”;}} {{t:e;o:“Manager”;e:“siri3@mailinator.com”;}}
To specify a signing order: {{t:e;o:“Role1”;e:“siri@mailinator.com”;order:1;}} {{t:e;o:“Client”;e:“siri2@mailinator.com”;order:2;}} {{t:e;o:“Manager”;e:“siri3@mailinator.com”;order:3;}}

Data Validators

Data validator - field or text tag parameter that specifies data format for the input.

Insert available formats from the table to your requests.

Or use GET /validator to obtain a list of available regular expression vaildators supported by signNow:

Name	Example	Unique ID	Description	Error message
DD/MM/YYYY	27/11/2008	059b068ef8ee5cc27e09ba79af58f9e805b7c2b3	Enter a date formatted dd/mm/yyyy	Enter a date formatted DD/MM/YYYY (e.g., 27/11/2008)
Date and Time	9/28/2008 3:49:00 PM	06448a0d0eb6a71c7c116ec4754bcb04ebf11da5	Enter a date and time formatted mm/dd/yyyy hh:mm:ss AM/PM format (AM/PM is optional)	Enter a valid date formatted mm/dd/yyyy hh:mm:ss am/pm (hh:mm:ss am/pm optional) e.g., 11/30/2003 10:12:24 am
DD-MON-YYYY Format	9-MAY-1981	07c1e60f3da1192b60aca6f7e72d9b17a44539e5	Enter a date formatted DD-MON-YYYY, in all caps and a hyphen between values	Enter a date formatted DD-MON-YYYY, in all caps and a hyphen between values e.g., 9-MAY-1981 or 29-FEB-2004
Time Only	3:49	09d3bb6a5eb6598edb7bfad02b0143d8c68ad788	Enter a time (hh:mm)	Enter a valid time formatted hh:mm or h:mm. e.g., 23:00
DD/MM/YY Format	31/12/75	0b61eb6a696da953910f195b30c86e5131f3ae3e	Enter a date formatted DD/MM/YY	Enter a valid date formatted DD/MM/YY e.g.,31/12/75 or 29/02/00
Mmm dd, yyyy Format	Jan 1, 2003 or December 12, 1999	0f4827a308018f98b11ae3923104685ff0c03070	Enter a date formatted Mmm dd, yyyy	Enter a valid date formatted Mmm dd, yyyy e.g., Jan 1, 2003 or December 12, 1999. The month must be capitalized, there cannot be a period, and there must be a comma.
Date Only	09/28/2008	13435fa6c2a17f83177fcbb5c4a9376ce85befeb	Enter a date mm/dd/yyyy	Enter a date e.g., mm/dd/yyyy
Number	1,234.50 or 1,234.05	1109cfbbb06311a06a4c7f8d04f1f0d5c44103cb	Enter a number, with or without decimal places or comma 1,000 separators	Enter a valid number, with or without decimal places or comma separators e.g., 12345 or 1,234.50 or 1,234.05
US Phone Number	(123) 456-7890	13cc1d661da456d27b249b73056ed4d1f2e72d8e	Enter a US phone number including area code	Enter a valid US phone number including area code e.g., (123) 456-7890
US Currency	$1,234.50	150662c7221a6a6ebcbb7c50ca46359d19757f81	Enter a dollar amount with commas for multiples of 1,000 and a period for the decimal	Enter a valid dollar amount with commas for multiples of 1,000 and a period for the decimal e.g. $1,234.50 or $1,234.05
US Zip Code	92663 or 92663-1234	1671f4eb87444a24e1e00f149bade8b7cf3af5da	Enter a 5 or 9 digit US zip code 92663 or 92663-1234	Enter a 5 or 9 digit US zip code formatted xxxxx-xxxx or xxxxx e.g., 92663 or 92663-1234
Age	29	1a203fa91791b0458608be045a454ba90557fb26	Enter an Age in years Maximum of 122	Enter a valid Age in years e.g., 29 or 68, with a maximum of 122
Positive Integers	12345	1f9486ae822d30ba3df2cb8e65303ebfb8c803e8	Enter a positive number using only digits 12345	Enter a valid positive number using only digits e.g., 12345
Positive or Negative Integers	1234 or -1234	23a57c29fa089e22bcf85d601c8091bc9c7da570	Enter a positive or negative integer 1234 or -1234	Enter a positive or negative integer e.g., 1234 or -1234 or +1234
US State	CA or NY	3123849de563f9e14acacc2739467e3d30e426b6	Enter a US state as you would for the Post Office	Enter a valid US state, as you would for the Post Office e.g., AL or CA
Alphanumeric (Letters & Numbers Only)	abc123	3859296fffd39cb8efeaffda5899973c014ce42e	Enter only letters and/or numbers	Enter only letters and/or numbers, with no special characters e.g., abc123 or 123abc
Email address	john@gmail.com, or john+1@gmail.com, or john123@gmail.com	7cd795fd64ce63b670b52b2e83457d59ac796a39	Enter an email address	Enter valid email address e.g., john+1@gmail.com or john123@gmail.com
Credit Card Number	4932271209947177	2f1c408bdf2f99fc5d4c342249da88ce5d2a5f02	Please enter a credit card number, hyphen or dot or space required	Enter a valid credit card number formatted xxxx-xxxx-xxxx-xxxx, e.g. 4932-2712-0994-7177
SSN	123-45-6789	2cd795fd64ce63b670b52b2e83457d59ac796a39	Please enter a Social Security Number (e.g. 123-45-6789 or 123456789)	Please enter a valid Social Security Number (e.g. 078-05-1120 or 078051120)

Event subscriptions

In Webhooks 2.0 signNow API introduces entities to set up the scope of events available for callbacks. The two entities you can now use are document and user. To set up the scope, {entity_id} is required for every event subscription.

At document scope, you receive callbacks after events involving a specific document. The {entity_id} == document_id in this case.

When you specify document_id, you receive callbacks when this document is signed. If it was sent to three signers, you receive one callback after the last signature.

See the Types of events for the query and callback payloads.

curl -L -X POST 'https://api.signnow.com//api/v2/events' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "event": "document.complete",
  "entity_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae",
  "action": "callback",
  "attributes": {
    "callback": "http://my-site.com",
    "use_tls_12": true,
    "docid_queryparam": true,
    "headers": {
      "string_head": "test",
      "int_head": 12,
      "bool_head": false,
      "float_head": 12.24
    }
  }
}'

At user scope , you receive callbacks after events involving a specific user. The {entity_id} == user_id in this case.

When you specify user_id and subscribe to user.document.complete, you receive callbacks after every signing of this user’s documents. In callbacks you receive the document_id that specifies which document was signed.

curl -X POST \
  https://api.signnow.com/api/v2/events \
  -H 'Authorization =  Bearer {{access_token}}' \
  -H 'Content-Type = application/json' \
  -d '{
  "event": "user.document.complete",
  "entity_id": "i3j4j0j38jccislfm04ijidcs7770sdjk2ooko4390dksjn",
  "action": "callback",
  "attributes": {
    "callback": "https://my.integration.com ",
    "use_tls_12": true,
    "integration_id": "Unique ID Integration System",
    "docid_queryparam": true,
    "headers": {
      "string_head": "test",
      "int_head": 12,
      "bool_head": false,
      "float_head": 12.24
    }
  }
}'

Retries [currently available only in Production environment]

signNow event processor marks callback task as 'success' when it gets 2xx HTTP response.

Service makes 10 more attempts to deliver a callback when callback returns 5xx HTTP response. Up to 5 retries are sent one by one immediately after getting 5xx response and then 5 more are sent - one every 4 hours.

Service marks callback task as 'failed' when it returns 5xx after all 5 retries.

Service marks callback task as 'failed' when callback returns 4xx HTTP response.

Callback subscription will be deactivated when callback returns 4xx 10 times in a row within one month.

Types of events

Document events

Event type	Meaning
`document.complete`	all required fields in the document have been filled in
`document.delete`	the document has been deleted
`document.open`	the document has been opened
`document.update`	the document has been edited

User’s actions with documents

Event type	Meaning
`user.document.complete`	in the specified user’s account a document has been completed
`user.document.create`	in the specified user’s account a document has been created
`user.document.delete`	in the specified user’s account a document has been deleted
`user.document.open`	in the specified user’s account a document has been opened
`user.document.update`	in the specified user’s account a document has been edited

Template events

Event type	Meaning
`template.copy`	a document has been generated from a template
`user.template.copy`	in the specified user’s account a document has been generated from a template

Field invite events

Field invite is an invite to sign the document which contains at least one Signature field.

More on field invites in Send a freeform or role-based invite

Event type	Meaning
`document.fieldinvite.create`	the field invite has been created for the specific document
`document.fieldinvite.decline`	the field invite for the specific document has been declined
`document.fieldinvite.delete`	the field invite for the specific document has been deleted
`document.fieldinvite.reassign`	the field invite for the specific document has been reassigned to a different address by the signer
`document.fieldinvite.sent`	the field invite for the specific document has been sent out to the signer(s)
`document.fieldinvite.signed`	all Signature fields in the specific document have been signed
`document.fieldinvite.replace`	the field invite for the specific document has been reassigned to a different address by the document owner

Field invite events triggered by Document Owner

Event type	Meaning
`user.document.fieldinvite.create`	in the specified user’s account a field invite has been created
`user.document.fieldinvite.decline`	in the specified user’s account a field invite has been declined
`user.document.fieldinvite.delete`	in the specified user’s account a field invite has been deleted
`user.document.fieldinvite.reassign`	in the specified user’s account a field invite has been reassigned to a different email address by the signer
`user.document.fieldinvite.sent`	in the specified user’s account a field invite has been sent
`user.document.fieldinvite.signed`	in the specified user’s account a field invite has been signed
`user.document.fieldinvite.replace`	in the specified user’s account a field invite has been reassigned to a different address by the document owner

Freeform invite events

Freeform invite - the invite to sign the document which has no fillable fields.

More on freeform invites in Send a freeform or role-based invite

Event type	Meaning
`document.freeform.create`	the freeform invite to sign the document was created
`document.freeform.signed`	the freeform invite has been signed

Freeform invite events triggered by Document Owners

Event type	Meaning
`user.document.freeform.create`	in the specified user’s account a freeform invite has been created
`user.document.freeform.signed`	in the specified user’s account a freeform invite has been signed

Embedded Signing

Embedded signing - having the documents signed within your website or app by creating an embedded invite.

1. Set up access to signNow API from your application.

Install the libraries to access signNow API from your application. In your Sandbox account you’ll find the Basic token for the test app.

# Install the PHP library via Composer

composer require signnow/api-php-sdk

# Or download the source directly: https://github.com/signnow/SignNowPHPSDK

2. Get Bearer token

Get Basic Authorization Token from the API Dashboard and request the Bearer token.

Organizations

Organization - a signNow entity which has a unique ID, logo, documents and templates, a Super Admin, other admins, Teams, and members.

Organizations can be created by signNow support team or by a subscription admin.

How do I create an organization?

To create an organization, a subscription admin should make a POST /v2/organizations request.

You may create multiple organizations per subscription. Each organization can have separate settings. Organizations may optionally be mapped to an email domain, to automatically assign users from different parts of your business.

Users on a Trial subscription can create up to 5 organizations, on a Professional or Enterprise subscription - up to 50.

Organization Super Admin

Organization Super Admin has full access to the organization and can view and delete other peoples documents and templates.

Super Admins only exist within enterprise accounts. To set up an enterprise account or create a super admin position, contact the signNow support team.

Organization Admin

Organization Admin has rights to create templates and send them out for signing as well as invite other teammates to the organization.

How do I add members/admins to an Organization?

To add Admins to an Organization, make a POST /v2/organizations/{{org_inique_id}}/admins request.

To add members to an Organization, make a POST /v2/organizations/{{org_inique_id}}/members request.

Organization Admin Panel

Organization Admin Panel, or the Organizational Dashboard, is an Enterprise only feature that allows organizations to manage multiple teams and view activity.

To access the panel, click on the Organization Admin Panel in the bottom left corner of the screen in your signNow account.

Dashboard

From the organizational dashboard, you can see all of your users and document stats, including documents created, documents sent for signing, documents completed, average completion time, and number of invite receipts.

Document Search

The search is implemented to find any document in the Organization faster. You can type any query in the basic search, or click Advanced Search and filter results by document name, signer email, document owner, or a text field.

Email Template

From there admins can set an Organization-wide email footer that will be added to each email sent by SignNow in the “Email Template” tab.

Team Settings

Track the activity of your Teams in this section. Select one to make it an Organization Team if you’re a member of several teams. Admins can select the default team to which each organization user will be added on sign up.

An Organization Team is a shareable team that your colleagues automatically get added to when they sign up for SignNow. Colleagues who already have SignNow accounts will also be added to this team.

Admin and Secondary Admins cannot view team member documents, and in order for your colleagues to be added to an organization team automatically, they need to have the same domain as you in the email address they register with.

Org Settings

Organization settings are available to organization admins only. Organization admins can be assigned by signNow support team. There are no limits on how many admins an Organization can have.

Team Templates

Under Team Templates, manage the list of templates available to all members of the Organization Team.

Cloud Storage

Once the Cloud Storage account is connected, Admins can check the Enable Export on Sign option. If it’s enabled, signed documents from all users’ accounts under the Organization will be automatically added to the export queue.

Merchant Account

Admin can also connect a Stripe account to signNow to later request payments on the documents.

Organization Settings

Super Admins can manage the Organization Settings via the Organization Admin Panel in their signNow account.

Settings that each User activates individually

Email notifications settings can be accessed from the user’s profile by clicking on the user’s icon from the top-right corner of the screen, selecting Profile and switching to the Notifications tab.

Settings that can be activated by Organization Admins

Organization settings are available in the Organization Admin Panel to organization admins only. Organization admins can be assigned by signNow support team. There are no limits on how many admins an Organization can have.

If a user is an Organization Admin, they will have the Organization Admin Panel button at the bottom-left corner of the screen.

Go to the Org Settings in the top menu. The available options are:

Mobile web

Allow Signer to Choose Between App or Mobile Web - adds the Sign with Mobile Browser option
Only Use Mobile Web - redirects signers to Mobile Web, without any mention of the App
Do Not Use Mobile Web - forces to download SignNow App

Drawloop Salesforce integration: set this option to On to integrate with your Drawloop account
Restrict Team Invites By Selected Team Admins: allows you to create a whitelist of admins that can invite members to Teams
Document Guide Option - determines whether to show or hide the Guide me wizzard to Signers of this Organization

Organization-wide Cloud Export

Organization Admins can access Cloud Storage settings under the Organization Admin Panel. Once the Cloud Storage account is connected, they can check the Enable Export on Sign option. If it’s enabled signed documents from all users’ accounts under the Organization will be automatically added to the export queue.

Team

Team - a signNow entity which has a unique ID, a Team Admin, Shared templates (in designated Shared Folders) and Team members.

How do I create a Team?

Create a team by clicking on the profile icon in the top right area of your browser and selecting View Teams.

In the Teams page, click Create New Team.

The Create a Team popup window allows you to name the team and invite members.

The Team admins can view team members’ documents checkbox gives you the option to allow or prohibit an admin to view all team members’ documents.

What’s the difference between adding a user and adding a team member?

Adding a new user
SignNow Subscription Admins can add a new user to their account and give that user a subscription along with access to all of the features associated with their account plan including sending documents out for signing.

To add a new user, visit your SignNow homepage and click Add User or do it using the Admin Console.

Adding a team member
A team member can only be invited by the team admin. Team members are only allowed to sign, send, and manage their documents across their team. However, they can’t create templates for other team members or monitor the status of another user’s activities. Only the team admin can monitor a user’s document that has been sent out for signing.

Admins can invite new members to the team even if they don’t have a SignNow account. In this case, the new team member must be assigned under the seat with the license, so they’re able to upload and send documents. Without the assigned license, they will only be able to view and with no further functionality.

Can a team admin see what documents are being sent by other team members?

When you create a team, you can choose to allow the team admin to be able to view all documents of other members or not. This setting is available when you click Create Team - the appeared pop-up has a specific checkbox.

If you tick the box, the team Admin - it can be you or other Admins - will be able to view all documents. If you don’t tick the box, the only documents Admins(s) will be able to view are those in the Shared Team Folder.

Note: At this time there is no way to change the setting for your teams. You must either create a team that allows you (the Admin) to view all documents or only templates in the Shared Folder. If you change your mind, you’ll have to deactivate the current team and create a new one with another setting.

To view team member documents, click on Action and choose View documentation.

Organization Team

Document Group

Document Group is an object with one ID that contains several documents. It helps automate signature requests for multiple documents from multiple signers.

What kind of documents can form a Document Group?

Must be owned by the person creating the Document Group.
Cannot be templates.
Cannot already be a part of another Document Group
If you’d like to add such documents anyway, first - delete the other document group that contains them.
To check if a document is a part of a Document Group, make a GET /document or GET /user/documents request. The "document_group_info" parameter must be an empty array. If it’s not empty and you’d like to use that document in another document group, copy a "document_group_id" from this array to delete that document group via a DELETE /documentgroup request.
At least one of the documents must have fields.
Documents don’t have field invites and signature requests ("field_invites" and "requests" parameters are both empty arrays)
Documents have not been signed (the "signature" parameter is an empty array)
Formats supported: PDF, DOCX

Before creating a Document Group, you should first have all the document IDs ready. Either save them from responses from the POST /document requests, or copy the IDs from the response from the GET /user/documents request.

Document Group Invite

Document Group Invite is an object for requesting signatures on a Document Group.

POST /documentgroup/{document_group_id}/groupinvite creates a multi-step invite for a document group. This allows the Document Group owner to specify the signing order and assign documents to their recipients correctly.

The Document Group Invite request body consists of two array objects: invite_steps and completion_emails.

In the invite_steps the Document Group owner specifies the following parameters and arrays:

”order” : integer, specifies the step when some signer(s) receive documents (starts with 1)
”invite_emails”: array object, contains the list of signer(s) for this step with an email address + email subject and message (optional parameters here ”reminder”, ”expiration_days”, ”disabled”)
”invite_actions”: array object, specifies who can sign the documents and who can only view them at a particular step by the email addresses mentioned in the ”invite_emails”. The available actions are "sign" and "view". Signer verification is available via a number of authentication methods.

Authentication methods:

      authentication_type: password
      password: 123456

      authentication_type: phone
      method: phone_call
      phone: +11111111111

      authentication_type: phone
      method: sms
      phone: +11111111111

Once all the invite_actions are completed, the next step’s invite emails are sent out. When all steps have been completed, completion emails are sent out.

In the completion_emails the Document Group owner sends confirmation emails to the recipients who have completed their actions.

Document Group Invite example

curl -L -X POST 'https://api-eval.signnow.com//documentgroup/{{document_group_id}}/groupinvite' \
-H 'Authorization: Bearer {{access_token}}' \
-H 'Content-Type: application/json' \
--data-raw '{
  "client_timestamp": 1586533427,
  "invite_steps": [
    {
      "order": 1,
      "invite_emails": [
        {
          "email": "signer1@email.com",
          "subject": "manager@email.com Needs Your Signature",
          "message": "manager@email.com invited you to sign 1",
          "expiration_days": 30,
          "reminder": 0
        },
        {
          "email": "signer2@email.com",
          "subject": "manager@email.com Sent You a Document",
          "message": "manager@email.com sent you 1",
          "expiration_days": 30,
          "reminder": 0
        }
      ],
      "invite_actions": [
        {
          "email": "signer1@email.com",
          "role_name": "Signer 1",
          "action": "sign",
          "document_id": "b89518d373b23d5c1d45d5c9af7953d1a868e4de",
          "allow_reassign": "0",
          "decline_by_signature": "0",
          "authentication": {
            "type": "phone",
            "method": "phone_call",
            "phone": "+1234543454"
          }
        },
        {
          "email": "signer1@email.com",
          "action": "view",
          "document_id": "b89518d373b23d5c1d45d5c9af7953d1a868e4de",
          "allow_reassign": "0",
          "decline_by_signature": "0"
        }
      ]
    },
    {
      "order": 2,
      "invite_emails": [
        {
          "email": "signer2@email.com",
          "subject": "manager@email.com Needs Your Signature",
          "message": "manager@email.com invited you to sign 1",
          "expiration_days": 30,
          "reminder": 0
        }
      ],
      "invite_actions": [
        {
          "email": "signer2@email.com",
          "role_name": "Signer 2",
          "action": "sign",
          "document_id": "b89518d373b23d5c1d45d5c9af7953d1a868e4de",
          "allow_reassign": "0",
          "decline_by_signature": "0"
        }
      ]
    }
  ],
  "completion_emails": []
}'