Skip to content

API Documentation

Jump to bottom
Nathan Buchar edited this page Mar 20, 2019 · 4 revisions
Table of Contents

Class: HelloWorks

new HelloWorks(config)

Create a new HelloWorks SDK client instance in order to make HelloWorks API requests from your Node.js app. In most cases, only one instance should exist per application.

Parameters
  • config Object

    • apiKeyId string

      The HelloWorks API key ID.

    • apiKeySecret string

      The HelloWorks API key secret.

Examples

  • Instantiate a new HelloWorks SDK client.

    const client = new HelloWorks({
  apiKeyId: 'AbCd1234AbCd1234',
  apiKeySecret: 'WxYz7890WxYz7890WxYz7890WxYz7890WxYz7890'
});

Back to top


Token


getToken()

client.token.getToken(options)

Gets a new JWT token.

Note: If you are using this SDK, the JWT token needed to make authorized API calls is generated behind the scenes. Only use this method if you specifically need to generate a new one. This will not update the JWT token used internally.

Parameters
  • options Object

    • apiKeyId string

      Your HelloWorks API key ID.

    • apiKeySecret string

      Your HelloWorks API key secret.

Resolves
{
  token: String,
  expires_at: Number
}
Examples

  • Gets a new JWT token. More information about this endpoint can be found in the HelloWorks API Documentation.

    client.token.getToken({
  apiKeyId: 'AbCd1234AbCd1234',
  apiKeySecret: 'WxYz7890WxYz7890WxYz7890WxYz7890WxYz7890'
}).then(({ token, expires_at }) => {
  // ...
});

Workflow Instances


createInstance()

client.workflowInstances.createInstance(options)

Creates a new workflow instance from the workflow with the given ID and the given set of options. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • workflowId string

      The ID of the Workflow that you want to create an instance of.

    • participants Array.<Participant>

      The participants parameters and its options for each of the roles. The initial role that's available is named signer.

    • mergeFields Object (optional)

      The merge fields for the Workflow Instance. This should be a nested object with Step IDs, field names, and values. See below for details.

    • callbackUrl string (optional)

      HTTPS URL for receiving a callback POST upon completion of the workflow instance.

    • redirectUrl string (optional)

      URL to redirect the user to upon completion of a signer step.

    • documentDelivery boolean (optional)

      Flag that this will mute notifications and allow teams to fetch an authenticated url.

      Defaults to false.

Resolves
{
  id: String,
  mode: String,
  steps: Step[]
}

See Type: Step.

Examples

  • Create a new workflow instance.

    client.workflowInstances.createInstance({
  workflowId: 'AbCd1234AbCd1234',
  participants: {
    signer: {
      type: 'email',
      value: '[email protected]',
      fullName: 'Lauren Ipsum'
    }
  }
}).then((instance) => {
  // ...
});

  • Create a new workflow instance with additional options.

    client.workflowInstances.createInstance({
  workflowId: 'AbCd1234AbCd1234',
  participants: {
    signer: {
      type: 'email',
      value: '[email protected]',
      fullName: 'Lauren Ipsum',
    },
  },
  mergeFields: {
    signerName_28XkWu: 'Lauren Ipsum',
  },
  callbackUrl: 'https://example.com/callback',
  redirectUrl: 'https://example.com/success',
  documentDelivery: true
}).then((instance) => {
  // ...
});

Back to top


getInstance()

client.workflowInstances.getInstance(options)

Gets the information for a given workflow instance. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • instanceId string

      The workflow instance ID.

Resolves

  • Completed workflow

    {
  id: String,
  workflow_id: String,
  status: String,
  type: 'workflow_stopped',
  mode: String,
  audit_trail_hash: String,
  document_hashes: {
    [Document ID]: String,
    // ...
  },
  data: {
    [Document ID]: {
      [Field]: String,
      // ...
    },
    // ...
  }
}

  • Pending workflow

    {
  id: String,
  workflow_id: String,
  status: String
}

  • Cancelled workflow

    {
  id: String,
  workflow_id: String,
  status: String,
  mode: String,
  data: {
    [Document ID]: {
      [Field]: String,
      // ...
    },
    // ...
  }
}
Example

  • Get the information on a workflow instance.

    client.workflowInstances.getInstance({
  instanceId: 'AbCd1234AbCd1234'
}).then((instance) => {
  // ...
});

Back to top


getInstanceSteps()

client.workflowInstances.getInstanceSteps(options)

Gets the instances steps for a given workflow instance. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • instanceId string

      The workflow instance ID.

Resolves
Step[]

See Type: Step.

Example

  • Get the instance steps for a workflow instance.

    client.workflowInstances.getInstanceSteps({
  instanceId: 'AbCd1234AbCd1234'
}).then((stepsArr) => {
  // ...
});

Back to top


getInstanceAuditTrail()

client.workflowInstances.getInstanceAuditTrail(options)

Gets the audit trail for a given workflow instance as a buffer for easy downloading. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • instanceId string

      The workflow instance ID.

Resolves

Buffer

Example

  • Download the workflow instance audit trail to file.pdf.

    const fs = require('fs');

client.workflowInstances.getInstanceAuditTrail({
  instanceId: 'AbCd1234AbCd1234'
}).then((buffer) => {
  fs.writeFile('file.pdf', buffer, (err) => {
    // ...
  });
});

Back to top


getInstanceDocument()

client.workflowInstances.getInstanceDocument(options)

Gets a document for a given workflow instance as a buffer for easy downloading. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • instanceId string

      The workflow instance ID.

    • documentId string

      The workflow instance document ID.

Resolves

Buffer

Example

  • Download the workflow instance document to file.pdf.

    const fs = require('fs');

client.workflowInstances.getInstanceDocument({
  instanceId: 'AbCd1234AbCd1234',
  documentId: 'WxYz'
}).then((buffer) => {
  fs.writeFile('file.pdf', buffer, (err) => {
    // ...
  });
});

Back to top


cancelInstance()

client.workflowInstances.cancelInstance(options)

Cancels a given workflow instance. More information about this endpoint can be found in the HelloWorks API Documentation.

Parameters
  • options Object

    • instanceId string

      The workflow instance ID.

Example

  • Cancel a workflow instance.

    client.workflowInstances.cancelInstance({
  instanceId: 'AbCd1234AbCd1234'
}).then(() => {
  // ...
});

Back to top


Type: Participant

Properties

  • type string

    The type of notification to send. email or phone.

  • value string

    The value corresponding to the type. If the type is email, the value should be the email of the recipient, or the phone number if the type is phone.

  • fullName string

    The full name of the associated type and value.

Back to top


Type: Step

Properties

  • step string

    The unique step ID.

  • role string

    The name of the role that will be completing the task.

  • participant string

    The signer's full name.

  • url string

    The unauthenticated url that can be used to start entering information.

Back to top


Having trouble? Let us know!

Welcome!

Below you will find links to the API documentation, frequently asked questions, and other useful tidbits.

Find something incorrect or missing? Shoot us an email or create an issue.

Having trouble? Let us know!

Clone this wiki locally