Signature Request - Bulk Create Embedded With Template | HelloSign API Documentation
Signature RequestContains information regarding documents that need to be signedContains information regarding documents that need to be signed
SignatureRequest Response Object.
test_mode Whether this is a test signature request. Test requests have no legal value. Defaults to 0.
signature_request_id The id of the SignatureRequest.
requester_email_address The email address of the initiator of the SignatureRequest.
title The title the specified Account uses for the SignatureRequest.
original_title Default Label for account.
subject The subject in the email that was initially sent to the signers.
message The custom message in the email that was initially sent to the signers.
metadata The metadata attached to the signature request.
created_at Time the signature request was created.
is_complete Whether or not the SignatureRequest has been fully executed by all signers.
is_declined Whether or not the SignatureRequest has been declined by a signer.
has_error Whether or not an error occurred (either during the creation of the SignatureRequest or during one of the signings).
final_copy_uri (Deprecated) The relative URI where the PDF copy of the finalized documents can be downloaded. Only present when is_complete = true. This will be removed at some point; use the files_url instead.
files_url The URL where a copy of the request's documents can be downloaded.
signing_url The URL where a signer, after authenticating, can sign the documents. This should only be used by users with existing HelloSign accounts as they will be required to log in before signing.
details_url The URL where the requester and the signers can view the current status of the SignatureRequest.
cc_email_addresses A list of email addresses that were CCed on the SignatureRequest. They will receive a copy of the final PDF once all the signers have signed.
signing_redirect_url The URL you want the signer redirected to after they successfully sign.
custom_fields An array of Custom Field objects containing the name and type of each custom field.
name The name of the Custom Field.
type The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.
value A text string for text fields or true/false for checkbox fields
required A boolean value denoting if this field is required.
api_id The unique ID for this field.
editor The name of the Role that is able to edit this field.
response_data An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
api_id The unique ID for this field.
signature_id The ID of the signature to which this response is linked.
name The name of the form field.
value The value of the form field.
required A boolean value denoting if this field is required.
type The type of this form field. See field types
signatures An array of signature obects, 1 for each signer.
signature_id Signature identifier.
signer_email_address The email address of the signer.
signer_name The name of the signer.
signer_role The role of the signer.
order If signer order is assigned this is the 0-based index for this signer.
status_code The current status of the signature. eg: awaiting_signature, signed, declined
decline_reason The reason provided by the signer for declining the request.
signed_at Time that the document was signed or null.
last_viewed_at The time that the document was last viewed by this signer or null.
last_reminded_at The time the last reminder email was sent to the signer or null.
has_pin Boolean to indicate whether this signature requires a PIN to access.
reassigned_by Email address of original signer who reassigned to this signer.
reassignment_reason Reason provided by original signer who reassigned to this signer.
error Error message pertaining to this signer, or null.
ACTION URI - Description
Embedded Bulk Send with Template
POST /signature_request/bulk_create_embedded_with_template
Creates BulkSendJob which sends SignatureRequests in bulk based off of a Template to be signed in an embedded window.
Description

Creates BulkSendJob which sends up to 250 SignatureRequests in bulk based off of the Template specified with the template_id parameter to be signed in an embedded iFrame. These embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.

NOTE: Only available for Gold plan and higher.

Request Parameters
test_mode optional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
client_id
The client ID of the ApiApp you want to associate with this request.
template_id or template_ids[%i%]
Use template_id to create a SignatureRequest from a single Template. Use template_ids[%i%] to create a SignatureRequest from multiple templates, where %i% is an integer indicating the order in which the template will be used. Only template_id or template_ids[%i%] can be used, not both.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
The URL you want the signer redirected to after they successfully sign.
signer_file or signer_list
signer_file is a CSV file defining values and options for signer fields. Required unless a signer_list is used, you may not use both. The CSV can have the following columns:
  • name: the name of the signer filling the role of RoleName
  • email_address: email address of the signer filling the role of RoleName
  • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
  • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
    Note: Not available in test mode and requires a Platinum plan or higher.
  • *_field: any column with a "_field" suffix will be treated as a custom field (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example CSV:
name, email_address, pin, company_field
George, george@example.com, d79a3td, ABC Corp
Mary, mary@example.com, gd9as5b, 123 LLC

signer_list is a JSON array defining values and options for signer fields. Required unless a signer_file is used, you may not use both. Each element in the array can have the following two items:
  • signers: an array of signers using the RoleName as keys (currently only one signer is supported per SignatureRequest)
    • name: the name of the signer filling the role of RoleName
    • email_address: email address of the signer filling the role of RoleName
    • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
    • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
      Note: Not available in test mode and requires a Platinum plan or higher.
  • custom_fields: an array of custom field values using the field name or API id as keys (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example JSON: 
[
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com",
        "pin": "d79a3td"
      }
    },
    "custom_fields": {
      "company": "ABC Corp"
    }
  },
  {
    "signers": {
      "Client": {
        "name": "Mary",
        "email_address": "mary@example.com",
        "pin": "gd9as5b"
      }
    },
    "custom_fields": {
      "company": "123 LLC"
    }
  }
]
custom_fields optional
A JSON array defining values and options for custom fields. You may also specify custom field values in the signer_list or signer_file, but all other options should be set here.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is set to 'true')
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
ccs[%RoleName%][email_address] optional
The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 1000 characters long.
Response
Returns a BulkSendJob object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/bulk_create_embedded_with_template
template_id = c26b8a16784a872da37ea946b9ddec7c1e11dff6
subject = Purchase Order
message = Glad we could come to an agreement.
signer_list = [{"signers":{"Client":{"name":"George","email_address":"george@example.com"}},"custom_fields":{"Cost":"$20,000"}}]
ccs[Accounting][email_address] = accounting@hellosign.com
client_id = 1a659d9ad95bccd307ecad78d72192f8