Send Signature Invites Using API

Automating your document signing process is a game-changer for any business or developer looking to streamline workflows and reduce manual effort. With the signNow API, you can send signature invites directly from your application, enabling seamless, secure, and efficient eSignature experiences for your users. This guide will walk you through everything you need to know about sending signature invites using the signNow API, including the differences between freeform and role-based invites, required parameters, best practices, and troubleshooting tips. Whether you're building a custom integration or enhancing an existing workflow, you'll find actionable insights and step-by-step instructions to get started quickly.

Understanding Signature Invites in the signNow API

Signature invites are at the heart of signNow's eSignature automation. They allow you to request signatures from one or more recipients on a document, either by letting signers place their signatures anywhere (freeform) or by assigning them to specific fields (role-based). The signNow API supports both methods, giving you the flexibility to match your workflow needs. Freeform invites are ideal for quick, ad-hoc signing, while role-based invites provide structure and control for multi-signer, multi-step processes. By leveraging these invite types, you can automate everything from simple approvals to complex, multi-party agreements.

Prerequisites and Authentication

Before you can send signature invites via the signNow API, you need to ensure a few prerequisites are met:

• signNow Account: You must have an active signNow account. If you don't have one, you can register here.
• API Access: Obtain your API credentials from the signNow Developer Portal. This includes your client ID and secret, which are required for authentication.
• OAuth 2.0 Authentication: All API requests must be authenticated using OAuth 2.0. This involves exchanging your credentials for an access token, which is then included in the Authorization header of your API requests.
• Document Upload: The document you wish to send for signing must be uploaded to your signNow account before you can send an invite.

Authentication is a critical step for security. The signNow API uses encrypted API signatures and access tokens to ensure only authorized users can send invites. For more details on API signatures and security, visit our authentication documentation.

Overview of Invite Types: Freeform vs. Role-Based

The signNow API supports two primary types of signature invites:

• Freeform Invites: Allow recipients to place their signature and other fields anywhere on the document. This is best for documents without predefined fillable fields and for quick, flexible signing scenarios.
• Role-Based Invites: Assign specific roles to signers and require them to complete designated fields in a set order. This is ideal for structured workflows where each signer has a defined responsibility.

Choosing the right invite type depends on your document and workflow requirements. Freeform invites offer speed and flexibility, while role-based invites provide control and compliance for more complex agreements.

How to Send a Freeform Signature Invite via API

To send a freeform invite, start by uploading your document to signNow. Ensure the document does not contain any fillable fields, as freeform invites are only available for such documents. Once uploaded, you can use an API client like Postman to compose your request. Set the HTTP method to POST and use the endpoint /document/{documentid}/invite. In the request body, specify the sender and recipient email addresses, subject, message, and any additional parameters. The sender's email must match your signNow login email. Here's an example of a freeform invite request: After sending the request, you can verify the invite was sent by checking your signNow dashboard. The recipient will receive an email with a link to sign the document, and they can place their signature anywhere. This process is ideal for quick, one-off signature requests where you don't need to control exactly where the signature appears.

How to Send a Role-Based Signature Invite via API

Role-based invites are used when your document contains predefined fields and you want to assign specific roles to signers. Start by uploading your document and adding fillable fields for each role. You can then use the API to send invites to multiple signers, specifying their roles, signing order, and additional parameters. In your API request, include a 'to' array with each signer's email, role, order, and any authentication or reminder settings. You can also add CC recipients and viewers, customize the subject and message, and set security options like password protection. Once the request is sent, each signer will receive an invite according to the specified order and role. Role-based invites are perfect for contracts, HR forms, or any workflow where multiple parties need to sign in a specific sequence.

Required and Optional Parameters for API Invites

When sending signature invites via the signNow API, it's important to understand which parameters are required and which are optional. Here’s a breakdown:

• Required Parameters (Freeform):
  • documentid: The unique ID of the uploaded document.
  • from: Sender's email address (must match your signNow login).
  • to: Recipient's email address.
  • subject: Email subject line.
  • message: Email message body.
  • oncomplete: Action to take after signing (e.g., 'documentandattachments').
• Required Parameters (Role-Based):
  • documentid: The unique ID of the uploaded document.
  • to: Array of signer objects, each with email, roleid, role, order, and other signer-specific settings.
  • from: Sender's email address.
  • subject: Email subject line.
  • message: Email message body.
  • oncomplete: Action to take after signing.
• Optional Parameters:
  • cc: Array of CC recipient emails.
  • ccstep: Array of CC step objects for advanced routing.
  • viewers: Array of viewer objects for read-only access.
  • reminder: Set to send reminders to signers.
  • expirationdays: Set an expiration date for the invite.
  • authenticationtype and password: Add extra security for signers.
  • reassign: Allow or prevent recipients from reassigning the invite.
  • declinebysignature: Allow signers to decline by signature.

Carefully review the API documentation for the full list of parameters and their usage: signNow API documentation.

Best Practices for Sending Signature Invites with the API

To ensure a smooth and secure signing experience, follow these best practices when sending signature invites via the API:

• Validate Email Addresses: Always check that sender and recipient emails are correct to avoid delivery issues.
• Use Secure Authentication: Protect sensitive documents by enabling password authentication or two-factor authentication for signers.
• Set Reminders and Expiration: Use reminder and expiration parameters to keep your signing process on track and avoid delays.
• Personalize Messages: Customize the subject and message fields to provide clear instructions and context for signers.
• Monitor Invite Status: Track the status of your invites through the signNow dashboard or API to ensure timely completion.
• Test in Sandbox: Use the signNow Developer Sandbox to test your API calls before deploying to production, minimizing errors and disruptions.

By following these guidelines, you can build robust, user-friendly eSignature workflows that delight your users and meet compliance requirements.

Troubleshooting Common Issues

Even with a well-designed API integration, you may encounter issues when sending signature invites. Here are some common problems and solutions:

• Authentication Errors: Double-check your OAuth 2.0 access token and ensure it hasn't expired. Refer to the authentication guide for troubleshooting tips.
• Invalid Document ID: Make sure the document has been uploaded successfully and the correct document ID is used in your API request.
• Missing Required Parameters: Review your request body to ensure all required fields are included and properly formatted.
• Email Delivery Issues: Confirm that recipient email addresses are valid and not blocked by spam filters.
• Invite Not Received: Ask recipients to check their spam or junk folders. If issues persist, resend the invite or contact signNow support.
• Role-Based Invite Errors: Ensure all roles and fields are correctly assigned in the document before sending the invite.

For more detailed troubleshooting, consult the signNow API documentation or reach out to our support team.

Frequently Asked Questions

Related articles