API Documentation (v2)

⚠️ Note: This article is intended for HelloSign Embedded v2. If you are using an older version of HelloSign Embedded, please refer to the documentation on our website.

Table of Contents

• Class: HelloSign
  • Methods
    • open()
    • close()
    • on()
    • once()
    • off()
  • Events
• Type: Signature
• Type: SignerRole
• Type: Options

---

Class: HelloSign

new HelloSign([options])

Create a new HelloSign Embedded client instance in order to embed a signature request into your webapp. In most cases, only one instance of HelloSign should exist per application. Any options specified when instantiating a new HelloSign Embedded client instance will be used as the config base when calling client.open().

Note: It should not be necessary to create a new client instance every time you want to call client.open().

Static Properties

• classNames Object

  An enum of class names used by HelloSign Embedded.

• events Object

  An enum of events emitted by a HelloSign Embedded client instance.

• locales Object

  An enum of locale codes supported by HelloSign.

• messages Object

  An enum of window event message types sent by the HelloSign app.

• version string

  The current version of HelloSign Embedded.

Instance Properties

• element HTMLElement

  The base element for HelloSign Embedded (if it is in the DOM).

• isOpen boolean

  Whether or not HelloSign Embedded is open.

• isReady boolean

  Whether or not the HelloSign app has initialized and is ready for signing.

Parameters

• options Object (optional)

  See Type: Options.

Examples

• Instantiate a new HelloSign Embedded client.

  const client = new HelloSign();

• Instantiate a new HelloSign Embedded client with options.

  const client = new HelloSign({
    clientId: 'Your client ID',
    debug: true,
    locale: HelloSign.locales.ZH_CN
  });

Back to top

Methods

A HelloSign Embedded client instance has the following public methods:

open()

client.open(url[, options])

Opens the HelloSign Embedded signature request window with the given URL. The provided URL can either be a signature sign_url, a signature request template edit_url, or a claim_url. See the HelloSign API documentation for more information. Options specified here will be merged with options specified when the client was instantiated (if any).

Emits open.

Parameters

• url string

  The url to open with HelloSign Embedded.

• options Object (optional)

  See Type: Options.

Examples

• Open the signUrl in the HelloSign Embedded client.

  client.open(signUrl);

• Open the signUrl in the HelloSign Embedded client with options.

  client.open(signUrl, {
    allowCancel: false,
    debug: true,
    locale: HelloSign.locales.ZH_CN
  });

Back to top

close()

client.close()

Closes the HelloSign Embedded signature request window if it is open.

Emits close.

Example

client.close();

Back to top

on()

Inherited from tiny-emitter. Documentation can be found here.

Examples

• Log when the signature request has been signed.

  client.on('sign', (data) => {
    console.log('The signature request was signed!');
  });

• Log when the signature request has been reassigned.

  client.on('reassign', (data) => {
    console.log(`The signature request was reassigned to ${data.email}`);
  });

Back to top

once()

Inherited from tiny-emitter. Documentation can be found here.

Examples

• Only once log when the signature request has been signed.

  client.once('sign', (data) => {
    console.log('The signature request was signed!');
  });

• Only once log when the signature request has been reassigned.

  client.once('reassign', (data) => {
    console.log(`The signature request was reassigned to ${data.email}`);
  });

Back to top

off()

Inherited from tiny-emitter. Documentation can be found here.

Examples

• Unsubscribe a single sign event listener.

  const handleSign = (data) => {
    console.log('The signature request was signed!');
  };
  
  client.off('sign', handleSign);

• Unsubscribe all sign event listeners.

  client.off('sign');

Back to top

Events

A HelloSign Embedded client instance emits the following events:

• cancel
• close
• createTemplate
• decline
• error
• finish
• message
• open
• ready
• reassign
• send
• sign

Event: 'cancel'

Emitted when the signature request or template was canceled by the user by either pressing the close button or selecting "close" from the "⋮" dropdown list.

Example

client.on('cancel', () => {
  console.log('The signature request was canceled');
});

Back to top

Event: 'close'

Emitted when the HelloSign Embedded window has closed.

Example

client.on('close', () => {
  console.log('The signature request window was closed');
});

Back to top

Event: 'createTemplate'

Emitted when the user has finished the template creation flow and it has been sent to HelloSign for processing. Note: the template might not be ready to use immediately. Before using a newly-created template, it is recommended that you first use the HelloSign SDK to determine the status of the template.

Data

• templateId string

  The template ID.

• templateInfo Object

  • title string

    The signature request template title.

  • message string

    The signature request template message.

  • signerRoles SignerRole[]

    The signature request template signer roles. See Type: SignerRole.

  • ccRoles string[]

    The signature request template CC roles.

Example

client.on('createTemplate', (data) => {
  console.log(`The signature request template "${data.templateInfo.title}" was created!`);
});

Back to top

Event: 'decline'

Emitted when the user declines the signature request by selecting "decline" from the "⋮" dropdown list (if allow_decline=1).

Data

• signatureId string

  The signature ID.

• reason string

  The reason given by the user why the signature request was declined.

Example

client.on('decline', (data) => {
  console.log(`The signature request was declined because "${data.reason}"`);
});

Back to top

Event: 'error'

Emitted when the HelloSign app encounters an error.

Data

• signatureId string

  The signature ID.

• code string

  One of the following error codes:

  • network_error - Lost connectivity
  • credentials_required - Login required
  • verify_email - Verify email step for template links
  • not_found - Resource not found
  • signer_choice - Must specify which signer they are
  • no_valid_signature_types - No signature type allowed due to settings
  • server_error - Generic server error
  • access_code_required - Must enter access code
  • access_code_invalid - Access code entered is invalid
  • access_code_blocked - Invalid access code entered too many times
  • nothing_to_sign - Nothing to signer or already signer
  • bad_request - Invalid request parameter(s)
  • bad_method - Unexpected HTTP method
  • unknown - Unknown exception

Example

client.on('error', (data) => {
  console.log(`Something went wrong! Please try again. Error code: ${data.code}`);

  client.close();
});

Back to top

Event: 'finish'

Emitted when the user has finished the embedded template or signature request flow without cancelling. However, the user may have declined or reassigned the signature request.

Example

client.on('finish', () => {
  console.log('The signature request was finished');
});

Back to top

Event: 'message'

Emitted when HelloSign Embedded has received a cross-origin window message from the HelloSign app.

Data

• type string

  The window event message type. See HelloSign.messages.

• payload ?Object

  Data relevant to the window message event, if applicable. Not all window message events will contain a payload.

Example

client.on('message', (data) => {
  if (data.type === HelloSign.messages.USER_SIGN_REQUEST) {
    console.log('The signature request was signed');
  }
});

Back to top

Event: 'open'

Emitted when the HelloSign Embedded window has opened.

Data

• url string

  The original URL.

• iFrameUrl string

  The final URL that will be embedded into the iFrame.

Example

client.on('open', (data) => {
  console.log(`The signature request was opened with ${data.iFrameUrl}`);
});

Back to top

Event: 'ready'

Emitted when the HelloSign app embedded in the iFrame has initialized and the signature request is ready.

Note: Embedded signing only.

Data

• signatureId string

  The signature ID.

Example

client.on('ready', (data) => {
  console.log(`The app has initialized the signature request (id: ${data.signatureId})');
});

Back to top

Event: 'reassign'

Emitted when the user reassigns the signature request by selecting "reassign" from the "⋮" dropdown list (if allow_reassign=1).

Data

• signatureId string

  The signature ID.

• name string

  The name of the reassignee.

• email string

  The email of the reassignee.

• reason string

  The reason given by the user why the signature request was reassigned.

Example

client.on('reassign', (data) => {
  console.log(`The signature request was reassigned to ${data.email} because "${data.reason}"`);
});

Back to top

Event: 'send'

Emitted when the user sends the signature request.

Data

• signatureRequestId string

  The signature request ID.

• signatureRequestInfo Object

  • title string

    The signature request title.

  • message string

    The signature request message.

  • signatures Signature[]

    The signature request signatures. See Type: Signature.

  • ccEmailAddresses string[]

    The signature request CC emails.

Example

client.on('send', (data) => {
  console.log(`The signature request was sent! (request id: ${data.signatureRequestId}`);
});

Back to top

Event: 'sign'

Emitted when the user signs the signature request.

Data

• signatureId string

  The signature ID.

Example

client.on('sign', (data) => {
  console.log(`The signature request was signed! (id: ${data.signatureId})`);
});

Back to top

Type: Signature

Properties

• signer_name string

  The signer's name.

• signer_email_address string

  The signer's email address. This is the email where the signature request will be sent to.

• order ?number

  The signer's position within a signature request. If there are multiple signers assigned to a signature request and order is enforced, all signers will be given a place in line. May be null.

Back to top

Type: SignerRole

Properties

• name string

  The role name.

• order number

  The role order.

Back to top

Type: Options

Properties

• allowCancel boolean

  History

  Version	Changes
  v2.0.1	Honored in embedded signing.

  Whether or not to allow the user to cancel the signature request by showing a close button.

  Default: true

• clientId string

  The client ID for your API app.

  Note: This must be specified in at least one place: either when instantiating a new HelloSign Embedded client, or in the options of client.open().

• container HTMLElement

  An HTML element in the DOM which the embedded signature request iFrame will be appended to. By default, HelloSign Embedded will open in a modal.

• debug boolean

  Whether or not to display debug information in the console from the HelloSign app.

  Default: false

• hideHeader boolean

  Whether or not to hide the signature request header. Only honored for customers with embedded branding.

  Default: false

• locale string

  History

  Version	Changes
  v2.9.0	The default value was removed. In older versions of HelloSign Embedded, if no locale was specified, then HelloSign Embedded would default to en-US. This was removed so that that web app can be used to determine an appropriate locale based on the user's default browser settings.

  The code for the language to use in the embedded request. Use HelloSign.locales to view an enumerable of supported locale codes. If this option is omitted, then the HelloSign web app will attempt to use the language defined by the user's default browser settings. If the language is not supported, then the web app will fall back to English.

  Note: Czech (cs-CZ) is only supported in Embedded Signing.

• redirectTo string

  A URL pointing to where to redirect to after the embedded signature request has been completed by the user.

• requestingEmail string

  The email of the account issuing the signature request.

  Note: This option is only necessary for Me and Others type signature requests. If it is required, either specify when instantiating a new HelloSign Embedded client, or in the options of client.open().

• skipDomainVerification boolean

  Whether or not to skip domain verification. Useful for testing signature requests on developer domains that don't match the API app's domain (like localhost).

  Note: Only honored if the signature request was created via the API with test_mode=1.

  Default: false

• testMode boolean

  History

  Version	Changes
  v2.2.0	Added.

  Alias of skipDomainVerification.

• timeout number

  How long (in milliseconds) to wait for the HelloSign app to initialize before aborting.

  Default: 30000 (30 seconds)

• whiteLabeling Object

  An object used to customize the signer experience for premium users with white-labeling capabilities. White labeling options can be found here.

• allowViewportOverride boolean

  History

  Version	Changes
  v2.11.0	Added.

  Allows HelloSign Embedded to override the viewport meta tag, if there is one, to improve behavior on small screens.

  Default: false

Back to top