This guide will assist you in integrating DocuSeal document e-signing capabilities into your Ruby on Rails application. With DocuSeal, you can create document templates from your PDF files, send them to the signers, and receive signed copies. Templates can be created either using our web UI or through the API. For instance, you can design a document template with various field types using HTML and CSS or PDF upload. More information on this can be found in our guides.
Before you begin making requests to our API, you need to obtain an authorization token so that we can identify you and your API requests.
To do this, you should register on our website if you haven't already and obtain an authorization token via Developer Console. The authorization token will look something like this:
ET6sBznGN42bTMEaNMkzAa
DocuSeal allows you to sign a document by one or multiple signatories. Each signing request is referred to as a "submission", and each signatory is called a "submitter". Let's take a look at an example of sending a signing request to one signatory.
You can send signing requests using an HTTP POST request to the address:
https://api.docuseal.co/submissions
In the request body, you should specify the following:
Each submitter should contain:
Here's an example of how to create a submission using the Faraday gem:
require 'faraday'
require 'json'
conn = Faraday.new(url: 'https://api.docuseal.co/submissions') do |f|
f.headers['X-Auth-Token'] = 'API_KEY' # Replace with your API key
f.headers['Content-Type'] = 'application/json'
end
response = conn.post do |req|
req.body = {
template_id: 1000001,
send_email: true,
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
}.to_json
end
puts response.body
DocuSeal API has many other parameters that you can use for sending signing requests. In this guide, we will only cover the most basic example so you can understand how it works. For more detailed information, you can refer to our documentation.
In the previous example, we used the API to send a signing request, but sometimes you may not have the opportunity to use the API or the DocuSeal web UI. Also, you may not always know the email of the signer, but you do know that they have visited your website. In such cases, you can use an embedded Signing form. This allows you to embed a Signing form on your website so that the signer can sign the document directly on your website. To embed the Signing form, you need to create a document template in our web UI or using our API and use the unique template ID.
Let's integrate a signing form into our web page using plain JavaScript for this example. To do this, you need to add the following code to your page:
<script src="https://cdn.docuseal.co/js/form.js"></script>
<script src="https://cdn.docuseal.co/js/form.js"></script>
<docuseal-form
id="docusealForm"
data-src="https://docuseal.co/d/LEVGR9rhZYf86M"> <!-- Unique template URL -->
</docuseal-form>
<script>
window.docusealForm.addEventListener('completed', (e) => e.detail)
</script>
After adding this code to your page, you will see such a signing form on your website. However, you can customize its appearance and behavior using many parameters. You can read more about this in our documentation.
After the signer has signed the document, DocuSeal can send you the sign results using a webhook. You can use these results to process the sign in your application. For example, you can save the signed document in your application. To do this, you need to specify the address of your server, to which we will send the sign results. You can do this in the webhooks settings.
DocuSeal can send you 3 types of webhooks:
Let's consider an example when the signer has completed filling out the Signing form, and a webhook has been sent to your server. To do this, you need to create a webhook handler on your server that will process the sign results.
In this example, we use Ruby on Rails and Faraday to create a simple server that listens for incoming webhooks and saves the signed documents to the local file system.
class WebhooksController < ActionController::API
def create
unless params[:event_type] == 'form.completed' || params.dig(:data, :documents).blank?
return head :unprocessable_entity
end
params[:data][:documents].each do |document|
response = Faraday.get(document['url'])
if response.success?
# Create an Active Storage blob from the StringIO
blob = ActiveStorage::Blob.create_and_upload!(
io: StringIO.new(response.body),
filename: "#{document['name']}.pdf"
)
ActiveStorage::Attachment.create!(
blob:,
name: 'document',
record: Document.find_by(id: params[:data][:external_id])
)
end
end
head :ok
end
end
In this guide, we have only covered the most basic example of using DocuSeal in a Ruby on Rails application. DocuSeal has many other capabilities that you can use to enhance your application. For example, you can embed not only the Signing form on your website but also the Form builder. You can also use the API to fully automate the process of generating custom documents using HTML and then sending them for signer without using the DocuSeal web UI. Additionally, you can host DocuSeal on your own server to gain the full ownership and control over your data.