Invite to sign

In signNow, the Invite to sign is the basic operation of sending a document for signature. Creating an Invite to sign involves: adding fillable fields to a document, specifying signers (their roles, names, and email addresses), assigning fields to signers, and setting the order of signing. There are two kinds of Invite to sign: a Freeform invite and a Field invite (a.k.a Role-based invite). With a Freeform invite, users can send documents without any fields.

The Invite to sign object contains:

  • "to": array with signers' details;
  • "from": sender's address
  • "cc": addresses of recipients who receive a CC but don't sign anything
  • "subject": email subject of the send invite
  • "message": email message describing the invite

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

The Invite object

Attributes
  • id string
    Unique identifier for the object.
  • document_id string
    Unique identifier of the document for signature.
  • to array[object]
    The array that contains data about signers.
  • email string
    Signer's email address.
  • role_id string
    Signer's role identifier.
  • role string
    Signer's role identifier in the document.
  • order string
    Integer: the order of signing.
  • from string
    Sender's email address.
  • cc string
    Email address for the CC recipients.
  • subject boolean
    Email subject for the signer notifying about the invite.
  • message array[object]
    Email message for the signer describing the invite.
More attributes
  • document_group_id string
  • data array[object]
  • auth_method string
  • first_name string
  • last_name string
  • link string
The Invite object
                { 
              
                  "to": [ 
              
                    { 
              
                      "email": "signer1@email.com", 
              
                      "role_id": "", 
              
                      "role": "Signer 1", 
              
                      "order": 1 
              
                    }, 
              
                    { 
              
                      "email": "signer2@email.com", 
              
                      "role_id": "", 
              
                      "role": "Signer 2", 
              
                      "order": 2 
              
                    } 
              
                  ], 
              
                  "from": "sender@email.com", 
              
                  "cc": [], 
              
                  "subject": "You’ve got a new signature request", 
              
                   "message": "Hi, this is an invitation email." 
              
                }
              

Send an invite to sign (document without fields)

Creates and sends a freeform invite to sign a document (invite for a document with no fields).

Parameters
  • document_id required
    Path parameter: ID of the requested document.
  • from required
    Sender's email address.
  • to required
    Signer's email address.
  • cc optional
    CC recipient's email address.
  • subject optional
    Custom email subject for the signer.
  • message optional
    Custom email message for the signer.
  • cc_subject optional
    CC recipient's email subject.
  • cc_message optional
    CC recipient's email message.
Returns

Returns success, the sent invite ID, and the callback URL if any. Returns an error when:

  • Invalid "to" email, "code": 65536. Message: "To must be a valid email."
  • Invalid "from" email, "code": 65536. Message: "From must be a valid email."
  • "From" email is not document owner, "code": 65536. Message: "Email not found"
  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Invalid document, "code": 65582. Message: "Document not found"
POST /document/{{document_id}}/invite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/document/{{document_id}}/invite \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
   "from":"sender@signnow.com",          
   "to":"signer.email@signnow.com"               
  } 
                      
                    
                      
api.document.invite({
  token: 'your auth token',
  id: 'document id',
  data: {
    from: 'email address',
    to: 'email address',
  },
}, (err, res) => {
  // handle error or process response data
});
                      
                    
                      
public static partial class InviteExamples
{
    /// <summary>
    /// Create a freeform invite to the document for signature.
    /// </summary>
    /// SignNow document you’d like to have signed
    /// The email of the invitee.
    /// Access token
    /// <returns>
    ///  which contains an Identity of invite request.
    /// </returns>
    public static async Task<InviteResponse>
        CreateFreeformInviteToSignTheDocument(SignNowDocument document, string email, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // Create freeform invite
        var invite = new FreeFormSignInvite(email)
        {
            Message = $"{email} invited you to sign the document {document.Name}",
            Subject = "The subject of the Email"
        };

        // Creating Invite request
        return await signNowContext.Invites.CreateInviteAsync(document.Id, invite).ConfigureAwait(false);
    }
}
                      
                    
                      
invite_payload = new
{
  "from": "account_email@domain.com",
  "to": "name@domain.com"
}

freeform_invite_res = signnow_python_sdk.Document.invite(access_token, "YOUR DOCUMENT ID", invite_payload)
                      
                    
Response
                {
    "result": "success",
    "id": "96c2bc976fab4f188171d7e6a8b49ee372ab9e7f",
    "callback_url": "none"
}
                
              

Send an invite to sign (document with fields)

Creates and sends a field invite to sign a document (invite for a document that contains fields).

Parameters
  • document_id required
    Path parameter: ID of the document.
  • document_id optional
    ID of the document for signature.
  • to required
    Array[object]: email addresses and settings for all recipients.
  • to[].email required
    Recipient's email address.
  • to[].role_id required
    ID of the recipient's Signer role. Can be optional if the role parameter is specified.
  • to[].role required
    Recipient's Signer role name. e.g. Signer 1, Signer 2. Can be optional if the role_id parameter is specified.
  • to[].order optional
    Integer, order of signing: 1 - the recipient has to sign the document first, then the document is sent to 2,3 etc. Several recipients can hold the same order of signing.
  • to[].prefill_signature_name optional
    Prefilled text in the Signature field, available for editing.
  • to[].force_new_signature optional
    Whether or not the signer can use their saved signature. Possible values: 0 - signer can use a saved signature, 1 - signer has to add a new signature.
  • to[].signing_instructions optional
    Pop-up message which guides the signer through the document.
  • to[].reassign optional
    Whether or not to allow recipients reassign this invite to another email address.
  • to[].decline_by_signature optional
    Whether or not to allow recipients decline the invite.
  • to[].reminder optional
    In how many days to send a reminder email to recipients
  • to[].expiration_days optional
    In how many days the invite expires.
  • to[].authentication_type optional
    Type of signer's identity verification. Possible values: password or phone.
  • to[].password required if "authentication_type": "password"
    Signer's verification password.
  • to[].phone required if "authentication_type": "phone"
    Signer's verification phone number.
  • to[].subject optional
    Custom email subject for the recipient.
  • to[].message optional
    Custom email message for the recipient.
  • to[].redirect_uri optional
    When all the requested fields are completed and signed, the signer is redirected to this URI.
  • from required
    Sender's email address: you can use only the email address associated with your signNow account (login email) as "from" address.
  • cc optional
    Array[string]: email addresses for CC recipients.
  • cc_step optional
    Array[string]: order and settings of sending the cc emails.
  • cc_step[].name optional
    Name of the step.
  • cc_step[].email optional
    CC recipient's email address.
  • cc_step[].step optional
    Integer: the order of sending, starting from 1
  • viewers optional
    Array[string]: array of recipients who will get read-only access to the invite.
  • viewers[].email optional
    Viewer's email address.
  • viewers[].role optional
    Viewer's role name.
  • viewers[].order optional
    Integer: the order of sending, starting from 1
  • subject optional
    Email subject for all signers.
  • message optional
    Email message for all signers.
  • cc_subject optional
    CC email subject for all CC recipients.
  • cc_message optional
    CC email message for all CC recipients.
Returns

Returns success if the request is correct. Returns an error when:

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Invalid "to" email, "code": 65536. Message: "To must be a valid email."
  • Invalid "from" email, "code": 65536. Message: "From must be a valid email."
  • Wrong role, "code": 65536. Message: "Role {{role_id_1}} does not exist on document"
  • Document doesn’t contain fields, "code": 65594. Message: "Cannot send a field invite: This document does not contain fields."
  • Send the same field invite for the second time, "code": 65629. Message: "Could not create duplicate field invite"
  • Invalid document, "code": 65582. Message: "Document not found"
  • Password or phone parameter for the authentication type is missing, "code": 65536. Message: "authentication type must not be empty"
POST /document/{{document_id}}/invite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/document/{{document_id}}/invite \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
  "document_id": "d9b490bd613e25cc5ec1a3b0b83dfccc164382bd",
  "to": [
    {
      "email": "signer1@email.com",  
      "role_id": "488d73a3efab032511f144af3a2572a8aae20162", 
      "role": "Signer 1", /  
      "order": 1, 
      "prefill_signature_name": "Signer 1",
      "force_new_signature": 1,
      "signing_instructions": "Please, add your signature here",
      "reassign": "0",
      "decline_by_signature": "0",
      "reminder": 0,
      "expiration_days": 30,
      "authentication_type": "password",
      "password": "123456",
      "subject": "You’ve got a new signature request",
      "message": "Hi, this is an invite to sign a document from sender@email.com."
    }
  ],
  "from": "sender@email.com", 
  "cc": [
    "sales@email.com",
    "hr@email.com"
  ],
  "cc_step": [
    {
      "name": "CC 1",
      "email": "sales@email.com",
      "step": 1
    },
    {
      "name": "CC 2",
      "email": "hr@email.com",
      "step": 2
    }
  ],
  "viewers": [
    {
      "email": "viewer@email.com",
      "role": "Viewer 1",
      "order": 1
    }
  ],
  "subject": "sender@email.com Needs Your Signature",
  "message": "sender@email.com invited you to sign the Invoice document",
  "cc_subject": "cc Invoice request",
  "cc_message": "cc Invoice request for Signer 1"
}
                      
                    
                      
const fieldInvite = {
  from: 'EMAIL_OF_SENDER',
  to: [
    {
      email: 'EMAIL_OF_SIGNER',
      role: 'Signer 1',
      order: 1,
      reassign: '0',
      decline_by_signature: '0',
      reminder: 4,
      expiration_days: 27,
      subject: 'Field invite Signer1',
      message: 'Message',
    },
  ],
};

api.document.invite({
  data: {
    ...fieldInvite,
  },
  id: 'DOCUMENT_ID_GOES_HERE',
  token: 'YOUR_AUTH_TOKEN',
}, (err, res) => {
  // handle error or process response data
});
                      
                    
                      
public static partial class InviteExamples
{
    /// <summary>
    /// Create a role-based invite to the document for signature.
    /// </summary>
    /// SignNow document with fields you’d like to have signed
    /// The email of the invitee.
    /// Access token
    /// <returns> without any Identity of invite request.</returns>
    public static async Task<InviteResponse>
        CreateRoleBasedInviteToSignTheDocument(SignNowDocument document, string email, Token token)
    {
        // using token from the Authorization step
        var signNowContext = new SignNowContext(token);

        // Create role-based invite
        var invite = new RoleBasedInvite(document)
        {
            Message = $"{email} invited you to sign the document {document.Name}",
            Subject = "The subject of the Email"
        };

        // Creates options for signers
        var signer = new SignerOptions(email, invite.DocumentRoles().First())
            {
                ExpirationDays = 15,
                RemindAfterDays = 7,
            }
            .SetAuthenticationByPassword("***PASSWORD_TO_OPEN_THE_DOCUMENT***");

        // Attach signer to existing roles in the document
        invite.AddRoleBasedInvite(signer);

        // Creating Invite request
        return await signNowContext.Invites.CreateInviteAsync(document.Id, invite).ConfigureAwait(false);
    }
}                      
                      
                    
                      
invite_payload = {
  "to": [
    {
      "email": "name@domain.com",
      "role_id": "",
      "role": "Role 1",
      "order": 1,
      "authentication_type": "password",
      "password": "SOME PASSWORD",
      "expiration_days": 15,
      "reminder": 5
    },
    {
      "email": "name@domain.com",
      "role_id": "",
      "role": "Role 2",
      "order": 2,
      "authentication_type": "password",
      "password": "SOME PASSWORD",
      "expiration_days": 30,
      "reminder": 10
    }
  ],
  "from": "your_account_email@domain.com",
  "cc": [
    "name@domain.com"
  ],
  "subject": "YOUR SUBJECT",
  "message": "YOUR MESSAGE"
};

role_based_invite_res = signnow_python_sdk.Document.invite(access_token, "YOUR DOCUMENT ID", invite_payload)
                      
                    
Response
                {                
 "status": "success"                   
}
                
              

Resend email invite

Resends an invite to sign a document.

Parameters
  • field_request_unique_id required
    Path parameter: ID of the invite to sign a document.
Returns

Returns success if the request is correct. Returns an error when:

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Send to a different email address, "code": 65536. Message: "Could not resend: routing out of order."
  • The invite has expired, "code": 65536. Message: "Could not resend expired invite."
  • Invalid field invite id, "code": 65536. Message: "could not resend"
PUT /fieldinvite/{{field_request_unique_id}}/resend
cURL
                      
curl -X PUT \               
  https://api-eval.signnow.com/fieldinvite/{{field_request_unique_id}}/resend \              
  -H 'Authorization: Bearer {{access_token}}' \
                      
                    
Response
                {                
 "status": "success"                   
}
                
              

Replace a signer: Step 1 - Delete

To replace a signer in the invite, API user should follow three steps: delete the invite to the current signer(1), replace a signer(2), and send the invite to the new signer(3). This endpoint allows you to delete the invite to the current signer.

Parameters
  • field_invite_id required
    Path parameter: ID of the document in the invite. You can find it in the response from GET /document/{{document_id}} request as the id parameter in the field_invites array.
Returns

Returns successful status if the request was correct. Returns an error when the request is sent with an invalid field invite ID.

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Wrong field invite id in endpoint: 66502. Message: "Field invite not found."
DELETE /field_invite/{{field_invite_id}}
cURL
                      
curl -X DELETE \          
  https://api-eval.signnow.com/field_invite/{{field_invite_id}} \        
  -H 'Authorization: Bearer {{access_token}}' \       
                      
                    
Response
                {                
 "status": "success"                   
}
                
              

Replace a signer: Step 2 - Replace

To replace a signer in the invite, API user should follow three steps: delete the invite to the current signer(1), replace a signer(2), and send the invite to the new signer(3). This endpoint allows you to replace a signer in the invite.

Parameters
  • email required
    New signer's email address.
  • role_id required
    The role id for the new signer. You can find it in the response from GET /document/{{document_id}} request as the role_id parameter in the field_invites array.
  • is_replace required
    Boolean: determines whether to use the subject, message, and order of signing specified in the invite to the previous signer. Possible values: "true" - yes, keep the subject, message, and order of signing from the previous signer's invite; "false" - use the subject, message, and the order of signing from this payload.
  • expiration_days optional
    In how many days the invite expires; 30 days max.
  • decline_by_signature optional
    Adds the Decline button to the Signature field for the signer. Possible values: 0 - no Decline button, 1- add the Decline button.
  • reminder optional
    In how many days to send a reminder to the signer; 30 days max.
  • authentication_type optional
    Type of recipient's identity verification. Possible values: "password" or "phone".
  • password required if "authentication_type": "password"
    Password requested for identity verification.
  • phone required if "authentication_type": "phone"
    Phone number requested for identity verification.
Returns

Returns a new invite ID if the request is successful. Returns an error when the request is sent with an invalid email or role ID.

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Invalid email, "code": 65538. Message: "Email must be a valid email."
  • Incorrect role id, "code": 65582. Message: "Role does not exist."
  • Send correct request for the second time, "code": 65615. Message: "Invite already exists."
POST /field_invite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/field_invite \        
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
  "email": "new_signer@email.com",     
  "role_id": "d9b491bd632e25cc5ec1a3b0b83dfccc164382bd",     
  "is_replace": true,
  "expiration_days": 30,
  "decline_by_signature": 0,
  "reminder": 0,
  "authentication_type": "password",
  "password": "123456"
} 
                      
                    
Response
                {                
 "id": "30e0ffbfe8d344d2ac97e47726160e722397543f"                   
}
                
              

Replace a signer: Step 3 - Send

To replace a signer in the invite, API user should follow three steps: delete the invite to the current signer(1), replace a signer(2), and send the invite to the new signer(3). This endpoint allows you to send the invite to the new signer.

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

Returns successful status if the request was correct. Returns an error when the request is sent with an invalid document ID.

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • No field invite created for the document, "code": 65615. Message: "Field invite missing on this document."
  • Incorrect document id, "code": 65582. Message: "Document not found."
POST /document/{{document_id}}/trigger_fieldinvite
cURL
                      
curl -X POST \          
  https://api-eval.signnow.com/document/{{document_id}}/trigger_fieldinvite \        
  -H 'Authorization: Bearer {{access_token}}' \       
                      
                    
Response
                {                
 "status": "success"                   
}
                
              

Cancel invite

Cancels an invite to a document.

Parameters
  • document_id required
    Path parameter: ID of the requested document.
  • reason required
    The reason for cancellation.
Returns

Returns successful status if the request was correct. Returns an error when the request is sent with an invalid document ID.

  • Invalid authorization, "code": 1537. Message: "invalid_token"
  • Incorrect document id, "code": 65582. Message: "Document not found."
  • Reason not specified, "code": 65536. Message: "The reason value must not be empty string."
PUT /document/{{document_id}}/fieldinvitecancel
cURL
                      
curl -X PUT \               
  https://api-eval.signnow.com/document/{{document_id}}/fieldinvitecancel \             
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: application/json' \       
  -d '{
  "reason": "Cancellation reason"
} 
                      
                    
                      
api.document.cancelFieldInvite({
  token: 'your auth token',
  id: 'document id',
}, (err, res) => {
  // handle error or process response data
});
                      
                    
                      
cancel_invite_res = signnow_python_sdk.Document.cancel_invite(access_token, "YOUR DOCUMENT ID");
                      
                    
Response
                {                
 "status": "success"                   
}