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 upload. 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.

Only integers are recognized as numeric values.

curl -X POST \
  https://api-eval.signnow.com/oauth2/token \
  -H 'Authorization: Basic {{basic_authorization_token}}' \
  -H 'content-type: multipart/form-data;' \
  -F 'username=user@email.com' \
  -F 'password={{password}}' \
  -F 'grant_type=password' \
  -F 'scope=*'

# 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));

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

The most commonly used authorization flow is creating access from a third-party application via grant type authorization_code. Grant type password is used for application owner’s accounts. They, in turn, provide access to signNow resources via three-legged OAuth using authorization_code.

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"
    }
  ]
}

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)	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

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;}}

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

Popular Field Sizes

Field Type	Purpose	Width & Height, Font Size 10	Width & Height, Font Size 12	Width & Height, Font Size 10
Text field	name	—	—	—
Text field	email address	—	—	—
Text field	US phone number	—	—	—
Signature field	for signing a document	—	—	—

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, “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, }

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": "user.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 [beta]

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": []
}'

Three-legged OAuth

signNow API allows third-party applications to access users’ resources in signNow account. All they need is to get a token with the authorization_code grant type.

Stages

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

Getiing 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}}'