module RightSignature::Document

Public Instance Methods

document_details(guid) click to toggle source

Gets details for a document

  • guids: Array of document GUIDs

Ex. Get details for document GUID123

@rs_connection.document_details("GUID123")
# File lib/rightsignature/document.rb, line 47
def document_details(guid)
  get "/api/documents/#{guid}.xml"
end
documents_batch_details(guids) click to toggle source

Gets details for multiple documents.

  • guids: Array of document GUIDs

Ex. Get details for documents GUID123 and GUID345

@rs_connection.documents_batch_details(["GUID123","GUID345"])
# File lib/rightsignature/document.rb, line 57
def documents_batch_details(guids)
  get "/api/documents/#{guids.join(',')}/batch_details.xml"
end
documents_list(options={}) click to toggle source

Lists documents

* <b>options</b>: (optional) search filters
  * <b>:state</b> - (completed/trashed/pending) filter by state
  * <b>:page</b> - page offset
  * <b>:per_page</b> - # of entries per page to return
  * <b>:search</b> - search term filter
  * <b>:tags</b> - tags filter. Array of ["single_tag", {"tag_key" => "tag_value"}]
  * <b>:sort</> - sort documents by given attribute.
  API supports 'created', 'completed', and 'activity'
  * <b>:range</b> - ('today'/'thisweek'/'thismonth'/'alltime'/Date) return documents with a certain date range.
  * <b> :recipient_email</b> - filter document where it has a recipient with given email and involves the current OAuth user.
  * <b> :account</b> - (true/false) include all documents in current account if true.

Ex.

options = {
  :state => ['completed', 'trashed'],
  :page => 1,
  :per_page => 20,
  :search => "me",
  :tags => ["single_tag", "key" => "with_value"]
}

@rs_connection.documents_list(options)
# File lib/rightsignature/document.rb, line 31
def documents_list(options={})
  if options[:metadata]
    options[:tags] = TagsHelper.array_and_metadata_to_string_array(options[:tags], options.delete(:metadata))
  elsif options[:tags]
    options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags])
  end
  options[:state] = options[:state].join(',') if options[:state] && options[:state].is_a?(Array)
  get "/api/documents.xml", options
end
extend_document_expiration(guid) click to toggle source

Extends a document's expiration date by 7 days

Ex. Extend expiration for document GUID123 by 7 days

@rs_connection.extend_document_expiration("GUID123")
# File lib/rightsignature/document.rb, line 88
def extend_document_expiration(guid)
  post "/api/documents/#{guid}/extend_expiration.xml", {}
end
generate_document_redirect_url(subject, recipients, document_data, options={}) click to toggle source

Prefills a document from a base64 encoded file or publicly available URL and returns a url that allows someone to send as the API User

  • document_data: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)

  • subject: subject of the document that'll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). One of the recipients requires :is_sender (true/false) to reference the API User and won't need to supply :name and :email Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer

    [
      {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
      {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
      {'is_sender' => true, :role => 'signer'},
    ]
    
  • options: other optional values

    • description: document description that'll appear in the email

    • action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs) Ex. ['sent_from_api', {“user_id” => “32”}]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. Ex. “yoursite/callback

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false. More info: rightsignature.com/apidocs/text_tags

Ex.

recipients = [
  {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
  {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]
document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
options = {
  :tags => ['sent_from_api', 'user_id' => '12345'],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.generate_document_redirect_url( "My Subject", recipients, document_data, options)
# File lib/rightsignature/document.rb, line 299
def generate_document_redirect_url(subject, recipients, document_data, options={})
  options[:action] = "redirect"
  response = send_document(subject, recipients, document_data, options)

  "#{site}/builder/new?rt=#{response['document']['redirect_token']}"
end
send_document(subject, recipients, document_data, options={}) click to toggle source

Creates a document from a base64 encoded file or publicly available URL

  • document_data: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)

  • subject: subject of the document that'll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). One of the recipients requires :is_sender (true/false) to reference the API User and won't need to supply :name and :email Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer

    [
      {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
      {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
      {'is_sender' => true, :role => 'signer'},
    ]
    
  • options: other optional values

    • description: document description that'll appear in the email

    • action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]
    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"
    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Ex.

recipients = [
  {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
  {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]
document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
options = {
  :tags => ['sent_from_api', 'user_id' => '12345'],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document( "My Subject", recipients, document_data, options)
# File lib/rightsignature/document.rb, line 246
def send_document(subject, recipients, document_data, options={})
  document_hash = {:document => {
    :subject => subject,
    :action => "send",
    :document_data => document_data
  }}

  document_hash[:document][:recipients] = []
  recipients.each do |recipient_hash|
    document_hash[:document][:recipients] << { :recipient => recipient_hash}
  end

  document_hash[:document].merge!(options)
  post "/api/documents.xml", document_hash
end
send_document_from_data(file_data, filename, subject, recipients, options={}) click to toggle source

Creates a document from a raw data

  • file: file binary. Ex. File.read('myfile.pdf')

  • filename: original filename

  • subject: subject of the document that'll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). One of the recipients requires :is_sender (true/false) to reference the API User and won't need to supply :name and :email Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer

    [
      {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
      {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
      {'is_sender' => true, :role => 'signer'},
    ]
    
  • options: other optional values

    • description: document description that'll appear in the email

    • action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs) Ex. ['sent_from_api', {“user_id” => “32”}]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. Ex. “yoursite/callback

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false. More info: rightsignature.com/apidocs/text_tags

# File lib/rightsignature/document.rb, line 123
def send_document_from_data(file_data, filename, subject, recipients, options={})
  send_document(subject, recipients, {:type => "base64", :filename => filename, :value => Base64::encode64(file_data)}, options)
end
send_document_from_file(file, subject, recipients, options={}) click to toggle source

Creates a document from a File or path to file

  • file: Path to file or File object

  • subject: subject of the document that'll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). One of the recipients requires :is_sender (true/false) to reference the API User and won't need to supply :name and :email Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer

    [
      {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
      {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
      {'is_sender' => true, :role => 'signer'},
    ]
    
  • options: other optional values

    • description: document description that'll appear in the email

    • action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]
    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"
    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Example:

recipients = [
  {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
  {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'}
]
options={
  :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document_from_file("here/is/myfile.pdf", 'My Subject', recipients, options)
# File lib/rightsignature/document.rb, line 164
def send_document_from_file(file, subject, recipients, options={})
  send_document(subject, recipients, {:type => "base64", :filename => File.basename(file), :value => Base64::encode64(File.read(file)) }, options)
end
send_document_from_url(url, subject, recipients, options={}) click to toggle source

Creates a document from URL

  • url: URL to file

  • subject: subject of the document that'll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). One of the recipients requires :is_sender (true/false) to reference the API User and won't need to supply :name and :email Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer

    [
      {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
      {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
      {'is_sender' => true, :role => 'signer'},
    ]
    
  • options: other optional values

    • description: document description that'll appear in the email

    • action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]
    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"
    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Example:

recipients = [
  {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
  {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'}
]
options={
  :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document_from_url("http://myfile/here", 'My Subject', recipients, options)
# File lib/rightsignature/document.rb, line 205
def send_document_from_url(url, subject, recipients, options={})
  send_document(subject, recipients, {:type => "url", :filename => File.basename(url), :value => url }, options)
end
send_reminder(guid) click to toggle source

Sends a reminder for a document

Ex. Sends reminder for document GUID123

@rs_connection.send_reminder("GUID123")
# File lib/rightsignature/document.rb, line 67
def send_reminder(guid)
  post "/api/documents/#{guid}/send_reminders.xml", {}
end
trash_document(guid) click to toggle source

Extends a document's expiration date by 7 days

Ex. Extend expiration for document GUID123 by 7 days

@rs_connection.trash_document("GUID123")
# File lib/rightsignature/document.rb, line 77
def trash_document(guid)
  post "/api/documents/#{guid}/trash.xml", {}
end
update_document_tags(guid, tags) click to toggle source

REPLACE the tags on a document tags are an array of 'tag_name' or {'tag_name' => 'value'}

Ex. Replaces document GUID123 with tags “single_tag”, “hello:bye”

@rs_connection.update_document_tags("GUID123", ["single_tag", {"hello" => "bye"}])
# File lib/rightsignature/document.rb, line 97
def update_document_tags(guid, tags)
  post "/api/documents/#{guid}/update_tags.xml", { :tags => TagsHelper.array_to_xml_hash(tags) }
end