API quickstart with the Ruby SDK

A Ruby SDK can be generated using the OpenAPI3 specification of our API and openapi generator. The package contains its own documentation (in docs/), but the examples below will show you how to get started.

Get your API Key

1. Sign up for a trial account. Configure for API when prompted and [email support](mailto:support@legalesign.com?subject=API key request) to get an API Key. You need to show a level of understanding about using REST API. Include a summary of your programming/REST experience.

2. Once issued, your API key will be available in the web app. You'll be in sandbox mode - use the form to enter emails for sending test documents.

3. Your api key goes in the "Authorization" header, and takes the form: Apikey username:secret. Your username and secret will be clearly indicated in the web app.

Install

1. Install Ruby.

2. Clone the Ruby package.

3. cd into the package, build the gem spec by typing: gem build openapi_client.gemspec

4. Install the gem by typing: gem install ./openapi_client-1.0.0.gem (sudo maybe required)

Test a GET request

Start with a basic GET request to make sure your Auth is correct.

require 'openapi_client'

OpenapiClient.configure do |config|
  config.api_key['Authorization'] = 'ApiKey username:secret'
end

api_instance = OpenapiClient::GroupApi.new
group_id = 'group_id_example' # String |

begin
  result = api_instance.get_group(group_id)
  p result
rescue OpenapiClient::ApiError => e
  puts "Exception when calling GroupApi->get_group: #{e}"
end

All being well, JSON text just appeared with your group information. If you have any issues, double and triple check your Auth.

It's common to need your latest signing document, use getDocuments, or getStatuses from the DocumentApi

api_instance = OpenapiClient::DocumentApi.new
statuses = api_instance.get_statuses(opts)
docs = api_instance.get_documents(opts)

Test a POST request

In this example we will send HTML, but you can upload a PDF/Word document or refer to a template you already prepared.

While HTML appears to be more primitive than a PDF it is most popular since it gives you a fast and full freedom in the construction of each document you send.

require 'openapi_client'

OpenapiClient.configure do |config|
  config.api_key['Authorization'] = 'ApiKey username:secret'
end

signers_data = [{ 'firstname' => 'john', 'lastname' => 'smith',
 'email' => 'john.smith@example.com', 'order' => 0}]

raw_html = '"<h1>Test doc</h1><p>Test doc 
for testing, <span class=\"field\"   data-optional=\"false\" 
data name=\"Please add your ...\" data-signee=\"1\"  
data-type=\"signature\" data-options=\"\"> ....... </span>'

post_data  = {
    'name' => 'Test html doc',
    'group' => '/api/v1/group/my-group/',
    'text' => raw_html,
    'do_email'=> true,
    'signers'=> signers_data
}

api_instance = OpenapiClient::DocumentApi.new
document_post = OpenapiClient::DocumentPost.new(post_data)

begin
    response = api_instance.post_document_with_http_info(document_post)
    status  = response[1] # 201
    doc_id = response[2]['Location'] # "/api/v1/status/4f746e7a-a661-4c4d-a28a-fe2bd59c263e/"

rescue OpenapiClient::ApiError => e
  puts "Exception when calling DocumentApi->post_document: #{e}"
end

How to get response headers from ruby openapi_generator SDK: append 'with_http_info' to the method name of your POST request. The response is a 3 item list comprising the response body, the status code, and the headers.

Upload and send a PDF You will most likely use text-tags within your PDFs, to define where people will sign or fill out any forms.

Learn more about text tags.

Lets upload a PDF using the 'with_http_info' version of the POST request to get the ID:

require 'openapi_client'
require 'base64'

OpenapiClient.configure do |config|
  config.api_key['Authorization'] = 'ApiKey username:secret'
end

api_instance = OpenapiClient::TemplatepdfApi.new

pdfdata = Base64.encode64(open("myfile.pdf").read)

data = {'group': '/api/v1/group/my-group/', 'pdf_file': pdfdata, 'title': 'test of tagged doc', 'process_tags': TRUE}

template_pdf_field_post = OpenapiClient::TemplatePdfFieldPost.new(data)
begin
    pdfresponse = api_instance.post_pdf_template_with_http_info(template_pdf_field_post)
rescue OpenapiClient::ApiError => e
  puts "Exception when calling TemplatepdfApi->post_pdf_template: #{e}"
end

Because we set process_tags to true, all the tags have been processed so your PDF is ready to go.

As before, we need the ID for the PDF so we can send it.

# 1. get ID of templatepdf object you just uploaded:

templatepdf_id = pdfresponse[2]['Location']

# 2. get the Document API if you haven't already:

docs = OpenapiClient::DocumentApi.new

# 3. construct post data and send, replace the group name and email (don't forget to use a sandbox email):

postdata = {
    'group': '/api/v1/group/my-group/',
    'name': 'test2', 'templatepdf': templatepdf_id,
    'signers': [{'order': 0, 'email': 'my@email.com', 'firstname': 'my', 'lastname': 'name'}],
    'do_email': TRUE
}

document_post = OpenapiClient::DocumentPost.new(postdata)

docs.post_document(document_post)

OR

docresponse = docs.post_document_with_http_info(postdata)
status  = docresponse[1]
doc_id = docresponse[2]['Location']

Get coding

Be sure to read the documentation. We had to dig around in the ruby source code a little but it is well laid out and consistent.

Some common gotchas are:

1. When you create a document, ensure your signers information is a Hash WITHIN a list (there may be more than 1 signer).

2. 404 may come back if your object references are wrong.

3. 401 will come back if you are in sandbox and try and send a document to someone not in your sandbox email list.

Happy coding!