Embedded signing

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

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.
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"
                       ,
                    
                  
                    
                            },
                    
                  
                    
                            {
                    
                  
                    
                              "email":
                       "signer2@email.com"
                       ,
                    
                  
                    
                              "role_id":
                       "1234567890dc4c7e8d897e2adad75b1234567890"
                       ,
                    
                  
                    
                              "order":
                       1
                       ,
                    
                  
                    
                              "auth_method":
                       "email"
                       ,
                    
                  
                    
                            }
                    
                  
                    
                          ]
                    
                  
                    
                        }'
                    
                  
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 or null.

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
                    {
                  
                      "status": "success"
                  
                    }