The embedded invite object

Attributes
  • data array[object]
    Array of invite objects for every signer role. Every signer gets their own invite according to the signing order.
  • id string
    Unique identifier of the invite.
  • email string
    Email address of the signer who carries the role.
  • role string
    The name of the role, e.g. Signer 1.
  • role_id string
    Unique identifier of the role.
  • order integer
    Always starts with 1: the step at which this signer is supposed to sign the document.
  • status string
    Invite status: pending (when sent), created (when still on hold until the previous signing step is completed), fulfilled (signed).
  • folders array[object]
    Child folders and their attributes.
  • total_documents integer
    How many documents in this folder.
  • documents array[object]
    Document objects stored in this folder and their attributes.
Example event subscription in response here:
                { 
              
                  "data": [ 
              
                    { 
              
                      "id": "03739a736d324f9794c2e93ec7c5bda817af3f7f", 
              
                      "email": "signer@email.com", 
              
                      "role_id": "33d7925969c53b55dfc2ea6d5d1fc8e788d33821", 
              
                      "order": 1, 
              
                      "status": "pending" 
              
                    }, 
              
                    { 
              
                      "id": "b926e550940746dda5206fa2bd8860ac7832b476", 
              
                      "email": "signer2@email.com", 
              
                      "role_id": "8844a3615c875a74358cefa09424617e00909f0a", 
              
                      "order": 1, 
              
                      "status": "pending" 
              
                    } 
              
                  ] 
              
                }
              

Create embedded signing invite

Creates embedded signing invites for a document without sending emails.

Once the invite is created, generate a link for it at POST v2/documents/{{document_id}}/embedded-invites/{{field_invite_id}}/link

Before composing your request, make sure that:

  • you are the owner of the document that you’d like to have signed
  • you are about to create an invite for a document, not a template
  • your document contains fields
  • your document doesn’t appear on any other invite, pending or signed
  • Signer’s emails are unique and don’t exceed 150 characters
  • all the roles or role IDs in the document are mentioned in the invite

Parameters role and role_id can be found in the response from GET /document/{{document_id}}. Specify a role either by role (unique role name, e.g. “Signer 1”), role_id (unique role identifier), or both. If you’ve chosen to add both, please make sure they correspond.

Parameters
  • document_id required
    Path parameter: ID of the requested document.
  • email required
    Signer's email address.
  • role_id required
    Signer's role ID.
  • order required
    Integer: order of signing. Cannot be 0.
  • auth_method required
    Signer authentication method.
  • first_name optional
    Recipient's first name used in the welcome message when they open the invite.
  • last_name optional
    Recipient's last name used in the welcome message when they open the invite.
Returns

Returns the invite data. Returns an error when:

  • Current user is not the document owner
  • Document has no active fields
  • Document has active invites
  • The role doesn’t exist in the document
  • Not all of the document roles were used
  • Document owner’s email was used as signer’s email
POST /v2/documents/{{document_id}}/embedded-invites
                    
                      curl 
                      -X POST
                       \
                    
                  
                    
                        '   http://api-eval.signnow.con/v2/documents/{{document_id}}/embedded-invites'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
                    
                        -H
                       'Content-type:
                       application/json'
                       \
                    
                  
                    
                        -d '{
                    
                  
                    
                          "invites": [
                    
                  
                    
                            {
                    
                  
                    
                              "email":
                       "signer@email.com"
                       ,
                    
                  
                    
                              "role_id":
                       "c8de4237e6dc4c7e8d897e2adad75b2b0b5ba659"
                       ,
                    
                  
                    
                              "order":
                       1
                       ,
                    
                  
                    
                              "auth_method":
                       "none"
                       ,
                    
                  
                    
                              "first_name":
                       "Pedro"
                       ,
                    
                  
                    
                              "last_name":
                       "Rodriguez"
                    
                  
                    
                            },
                    
                  
                    
                            {
                    
                  
                    
                              "email":
                       "signer2@email.com"
                       ,
                    
                  
                    
                              "role_id":
                       "1234567890dc4c7e8d897e2adad75b1234567890"
                       ,
                    
                  
                    
                              "order":
                       1
                       ,
                    
                  
                    
                              "auth_method":
                       "email"
                       ,
                    
                  
                    
                              "first_name":
                       "Alex"
                       ,
                    
                  
                    
                              "last_name":
                       "Green"
                    
                  
                    
                            }
                    
                  
                    
                          ]
                    
                  
                    
                        }'
                    
                  
Response
                        {
                      
                          "data": [
                      
                            {
                      
                              "id": "03739a736d324f9794c2e93ec7c5bda817af3f7f",
                      
                              "email": "signer@email.com",
                      
                              "role_id": "33d7925969c53b55dfc2ea6d5d1fc8e788d33821",
                      
                              "order": 1,
                      
                              "status": "pending"
                      
                            }
                      
                            {
                      
                              "id": "b926e550940746dda5206fa2bd8860ac7832b476",
                      
                              "email": "signer2@email.com",
                      
                              "role_id": "8844a3615c875a74358cefa09424617e00909f0a",
                      
                              "order": 1,
                      
                              "status": "pending"
                      
                            }
                      
                          ]
                      
                        }
                      

Generate a link for embedded invite

Creates a link for the embedded invite.

Copy the field invite unique ID from the response to POST /v2/documents/{{documentUniqueId}}/embedded-invites. It’s in the id parameter of every invite object.

                  {
                
                    "id": "03739a736d324f9794c2e93ec7c5bda817af3f7f",
                
                    "email": "signer@email.com",
                
                    "role_id": "33d7925969c53b55dfc2ea6d5d1fc8e788d33821",
                
                    "order": 1,
                
                    "status": "pending"
                
                  }
                

In your request specify: "auth_method" - signer authentication menthod; can be “password”, “email”, “mfa”, “social”, “biometric”, “other”, “none” "link_expiration" - in how many minutes the link expires, ranges from 15 to 45 minutes.

Parameters
  • document_id required
    Path parameter: ID of the requested document.
  • fieldInviteUniqueId required
    Path parameter: ID of the signature invite you'd like to embed. Can be copied from response to POST /v2/documents/{{documentUniqueId}}/embedded-invites
  • auth_method required
    Signer authentication menthod; can be “password”, “email”, “mfa”, “social”, “biometric”, “other”, “none”.
  • link_expiration required
    In how many minutes the link expires, ranges from 15 to 45 minutes or null.
Returns

Returns a link for embedded invite. Returns an error when either incorrect document or field invite ID is provided in the header.

POST /v2/documents/{{document_id}}/embedded-invites/{{fieldInviteUniqueId}}/link
                    
                      curl 
                      -X POST
                       \
                    
                  
                    
                        '  https://api-eval.signnow.com/v2/documents/{{document_id}}/embedded-invites/{{fieldInviteUniqueId}}/link'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
                    
                        -H
                       'Content-type:
                       application/json'
                       \
                    
                  
                    
                        -d '{
                    
                  
                    
                       "auth_method":
                       "none"
                       ,
                    
                  
                    
                       "link_expiration":
                       15
                    
                  
                    
                        }'
                    
                  
Response
                    {
                  
                      "data":
                  
                        {
                  
                          "link": "https://app.signnow.com/webapp/document/016c8d15f909003085ed074a06236bc50bb3e1c3?access_token=b6dbde12f21cf09cb795e73e6947a33a2fe728e28d4c99dacbed0649dc710b65&route=fieldinvite"
                  
                      }
                  
                    }
                  

Delete embedded invites

Deletes embedded invites for a document.

Parameters
  • document_id required
    Path parameter: ID of the requested document.
Returns

Returns success when all parameters are correct. Returns error when:

  • Current user is not the document owner
  • Document not found
  • The document has no active embedded invites
DELETE /v2/documents/{{document_id}}/embedded-invites
                    
                      curl 
                      -X DELETE
                       \
                    
                  
                    
                        '  https://api-eval.signnow.com/v2/documents/{{document_id}}/embedded-invites'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
Response (204)
                    {
                  
                     No content
                  
                    }
                  

Create embedded invite for a document group

Creates embedded signing invites for a document group.

Once the invite is created, generate a link for it by POST v2/document-groups/{{doc_group_id}}/embedded-invites/{{group_invite_id}}/link

Before composing your request, make sure that:

  • you are the owner of the document group that you’d like to have signed
  • each document in the payload is a part of a document group
  • your document group contains at least one document
  • your document group doesn’t appear on any other invite, pending or signed
  • at least one document in document group contains fields
  • all the roles or role IDs in the document are mentioned in the invite

Parameters role and role_id can be found in the response from GET /document/{{document_id}}. Specify a role either by role (unique role name, e.g. “Signer 1”), role_id (unique role identifier), or both. If you’ve chosen to add both, please make sure they correspond.

Parameters
  • document_group_id required
    Path parameter: ID of the document group to be embedded and signed.
  • invites required
    Array of invite objects that includes order of signing and settings for different signers.
  • order required
    Signing order step. On "order": 1, all signers of this step receive an email with the invite at the same time. Only when they complete all the actions, the "order": 2 emails are sent.
  • signers required
    Array of signer objects that must receive their invites at this step. Each signer object contains: signer's email address, authentication method, documents they are invited to sign, and the role assigned to them in the documents.
  • email required
    Signer’s email to receive the invite.
  • auth_method required
    Authentication method for the signer. Possible values: none, password, email, mfa, social, biometric, other
  • documents required
    Array of documents in the document group that the signer is invited to sign. For each document in the array, the document ID, signer role, and signer action are specified.
  • id required
    In the "documents" array: ID of the document
  • role required
    In the "documents" array: signer role in the document
  • action required
    In the "documents" array: signer action required in the document. Possible values: sign, view.
  • sign_as_merged required
    Boolean: if "true", signer can open all documents of the group in one signing session
Returns

Returns the ID of the created invite object. Returns an error when:

  • Current user is not the document group owner
  • Document group has no document with fields
  • Document group (or any of the documents) has active invites
  • The role doesn’t exist in the document
  • Not all of the document roles were used
  • Document owner’s email was used as signer’s email
POST /v2/document-groups/{{document_group_id}}/embedded-invites
                    
                      curl 
                      -X POST
                       \
                    
                  
                    
                        '   http://api-eval.signnow.con/v2/document-groups/{{document_group_id}}/embedded-invites'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
                    
                        -H
                       'Content-type:
                       application/json'
                       \
                    
                  
                    
                        -d '{
                    
                  
                    
                          "invites": [{ 
                    
                  
                    
                            "order":
                       "1"
                      ,
                    
                  
                    
                            "signers": [{ 
                    
                  
                    
                              "email":
                       "signer@email.com"
                       ,
                    
                  
                    
                              "auth_method":
                       "none"
                       ,
                    
                  
                    
                              "first_name":
                       "Pedro"
                       ,
                    
                  
                    
                              "last_name":
                       "Rodriguez"
                       ,
                    
                  
                    
                              "documents":[{ 
                    
                  
                    
                                "id":
                       "190c94e0d22742ee9c49ee67a40449ea305925fd"
                       ,
                    
                  
                    
                                "role":
                       "Signer 1"
                       ,
                    
                  
                    
                                "action":
                       "sign"
                    
                  
                    
                              },{
                    
                  
                    
                                "id":
                       "063c813deab044f4b6b0bf64fb180f27f17c1626"
                       ,
                    
                  
                    
                                "action":
                       "view"
                    
                  
                    
                              }]
                    
                  
                    
                            },{
                    
                  
                    
                              "email":
                       "signer2@email.com"
                       ,
                    
                  
                    
                              "auth_method":
                       "none"
                       ,
                    
                  
                    
                              "first_name":
                       "Alex"
                       ,
                    
                  
                    
                              "last_name":
                       "Green"
                       ,
                    
                  
                    
                              "documents":[{ 
                    
                  
                    
                                "id":
                       "063c813deab044f4b6b0bf64fb180f27f17c1626"
                       ,
                    
                  
                    
                                "role":
                       "Signer 2"
                       ,
                    
                  
                    
                                "action":
                       "sign"
                    
                  
                    
                              }]
                    
                  
                    
                            }]
                    
                  
                    
                          },{
                    
                  
                    
                            "order":
                       "2"
                      ,
                    
                  
                    
                            "signers": [{ 
                    
                  
                    
                              "email":
                       "signer@email.com"
                       ,
                    
                  
                    
                              "auth_method":
                       "none"
                       ,
                    
                  
                    
                              "documents":[{ 
                    
                  
                    
                                "id":
                       "190c94e0d22742ee9c49ee67a40449ea305925fd"
                       ,
                    
                  
                    
                                "role":
                       "Signer 1"
                       ,
                    
                  
                    
                                "action":
                       "sign"
                    
                  
                    
                              }
                    
                  
                    
                            }] 
                    
                  
                    
                          }], 
                    
                  
                    
                          "sign_as_merged":
                       "true"
                    
                  
                    
                        }'
                    
                  
Response
                        {
                      
                          "data": [
                      
                            {
                      
                              "id": "03739a736d324f9794c2e93ec7c5bda817af3f7f",
                      
                            }
                      
                        } 
                      

Generate a link for embedded doc group invite

Creates a link for the embedded doc group invite.

Copy the document group invite unique ID from the response to POST /v2/documents/{{document_group_id}}/embedded-invites. It’s in the id parameter.

                        {
                      
                          "data": [
                      
                            {
                      
                              "id": "03739a736d324f9794c2e93ec7c5bda817af3f7f",
                      
                            }
                      
                        } 
                      

In your request specify: "email" - signer's email address; "auth_method" - signer authentication menthod; can be “password”, “email”, “mfa”, “social”, “biometric”, “other”, “none”; "link_expiration" - in how many minutes the link expires, ranges from 15 to 45 minutes or null.

Parameters
  • document_group_id required
    Path parameter: ID of the embedded document group.
  • groupInviteUniqueId required
    Path parameter: ID of the embedded doc group invite you'd like to generate a link for. Can be copied from response to POST /v2/document-groups/{{document_group_id}}/embedded-invites
  • email required
    Signer's email address
  • auth_method required
    Signer authentication menthod; can be “password”, “email”, “mfa”, “social”, “biometric”, “other”, “none”.
  • link_expiration required
    In how many minutes the link expires, ranges from 15 to 45 minutes or null.
Returns

Returns a link for embedded invite. Returns an error when either incorrect document or field invite ID is provided in the header.

POST /v2/documents/{{document_id}}/embedded-invites/{{fieldInviteUniqueId}}/link
                    
                      curl 
                      -X POST
                       \
                    
                  
                    
                        '  https://api-eval.signnow.com/v2/documents/{{document_group_id}}/embedded-invites/{{groupInviteUniqueId}}/link'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
                    
                        -H
                       'Content-type:
                       application/json'
                       \
                    
                  
                    
                        -d '{
                    
                  
                    
                       "email":
                       "signer@email.com"
                       ,
                    
                  
                    
                       "auth_method":
                       "none"
                       ,
                    
                  
                    
                       "link_expiration":
                       15
                    
                  
                    
                        }'
                    
                  
Response
                    {
                  
                      "data":
                  
                        {
                  
                          "link": "https://app.signnow.com/webapp/document/016c8d15f909003085ed074a06236bc50bb3e1c3?access_token=b6dbde12f21cf09cb795e73e6947a33a2fe728e28d4c99dacbed0649dc710b65&route=fieldinvite"
                  
                      }
                  
                    }
                  

Delete embedded doc group invites

Deletes embedded invites for a document group.

Parameters
  • document_group_id required
    Path parameter: ID of the requested document group.
Returns

Successful response returns no content. Returns error when:

  • Current user is not the document group owner
  • Document group not found
  • The document group has no active embedded invites
DELETE /v2/document-groups/{{document_group_id}}/embedded-invites
                    
                      curl 
                      -X DELETE
                       \
                    
                  
                    
                        '  https://api-eval.signnow.com/v2/document-groups/{{document_group_id}}/embedded-invites'
                       \
                    
                  
                    
                        -H
                       'Authorization:
                       Bearer {{access_token}}'
                       \
                    
                  
Response (204)
                    {
                  
                     No content
                  
                    }