Workflow API

Workflow API

Introduction

Welcome to the SIGN8 Workflow API! This guide is designed to help you integrate our Workflow API seamlessly into your system. The Workflow API provides core functionality for managing workflows within third-party systems and enables efficient handling of interfaces, files, signatures and signatories.


What is the Workflow API?

The Workflow API offers all essential workflow functions for integration with third-party systems. It simplifies the workflow management process and enables the smooth integration and operation of SIGN8 signature workflows in your system.


First steps

To access our Workflow API, you need to purchase an Enterprise or volume-based subscription plan. Follow the steps below after purchase:


Step 1: Request integration access: contact our team and let them know that you would like to integrate our solution into your system. Our developers will provide you with the necessary access.

Step 2: Access the documentation: Navigate to the Administration section in your web application. There you will find the API button; clicking on it will give you access to the technical documentation for your developers.

Step 3: Access to systems: Accessing the documentation will give you access to the production system and the test system. This allows you to develop and test your integration in a controlled environment.


Test API workflow

Before you make changes to your system, it is advisable to test the functionality of our API workflow in a controlled environment. Here you can find out how to do this with Postman:

Step 1: Prepare a test environmentSet up a test environment in Postman that mimics the configuration and parameters of your system. This includes configuring variables for workflow details, file data, signer information, etc.

Step 2: Import the API documentationImport our workflow API documentation into Postman to access the available endpoints and request methods. This documentation contains details on how to structure your requests and handle responses.

Step 3: Review the resultsReview the responses of each request to ensure that they meet your expectations and that there are no errors or inconsistencies.

Use Postman's testing features to automate the review process and compare the expected results with the actual results.


Implementation

To implement our API workflow in your system, follow these first steps:

AddWorkflow (POST) - Provide workflow configuration:

  1. Enter workflow configuration details such as name, description and webhook configuration to start the workflow setup process.
  2. After adding the workflow, our database will generate a unique workflow ID and send it back to you.

AddFile (POST) - Provide file data:

  1. Configure the file data including name, type, XFDF (XML Forms Data Format) and base64 encoding.
  2. Use the received workflow ID to link the file to the corresponding workflow.
  3. Convert PDF files to XFDF format for seamless integration. More information about the conversion process can be found here: (add link)
  4. After successful submission, you will receive a file ID to identify and manage the uploaded file within the workflow.

AddSigner (POST) - Provide signer configuration:

  1. Configure signer details such as signature type, phone number, name, email, etc. for the specified workflow.
  2. Use the workflow ID to link signers to the respective workflow.
  3. Use the ‘addSigner’ function to seamlessly add signers to the workflow.

AddSignature (POST) - Provide signature data:

  1. Submit signature data, including the file ID, XFDF, position, page and signer ID to initiate the signing process.
  2. Use the ‘Add Signature’ function (HTTP PUT method) to attach signatures to the specified file within the workflow.
  3. Ensure that all required parameters are specified correctly to enable smooth placement of the signature.

AddAnnotation (POST) - Add additional annotations: (Optional)

  1. Optionally add relevant annotations or comments to provide additional context or instructions within the document to be signed.
  2. AddInterface (POST) - Customise the interface settings: (Optional)
  3. Customise the interface settings by including your company's logo and colours to maintain brand consistency and improve usability.


Name

Default value

Mandatory

[PK] Interface ID

interface_id

public.gen_random_uuid()

Yes

organization_id

organization_id

-

Yes

Primary color

primary_color

Default_sign8_color

Yes

Icon

icon_file_id

Default_sign8_icon_file_id

Yes

Logo

icon_file_id

Default_sign8_logo_file_id

Yes

Create timestamp

created_at

Current_timestamp

Yes

Update timestamp

updated_at

Current_timestamp

Yes

[PK] Primary key

Set up signature link:

Configure signature links sent by email or other communication channels to invite signatories to access and complete the workflow.

Provide signatories with direct links to the workflow to ensure seamless access to the signing process.

By following these steps, you can seamlessly integrate our workflow API into your system, enabling efficient workflow management and electronic signature processes.



Use Cases

Webhook for rejected workflow

In this use case, you can set up a webhook to receive notifications when a workflow has been rejected. This allows your system to take appropriate action based on the rejection of a workflow.

- Webhook URL: {{webhook_url}}/api/workflow/workflowRefused

- Method: POST

- Headers:

§ organisation_id: {{organisation_id}}

  • created_by: {{user_id}}
  • webhookPassword: {{webhook_password}}

If a workflow is rejected, the workflow API triggers this webhook and sends a POST request to the specified URL. Your system can then handle the rejection event accordingly, e.g. notify the relevant participants or update the workflow status.

Webhook for workflow has expired

Similarly, you can configure a webhook to receive notifications when a workflow has expired. This allows your system to take the necessary action in response to expired workflows.

  • Webhook URL: {{webhook_url}}/api/workflow/workflowExpired
  • Method: POST
  • Headers:
    • organisation_id: {{organisation_id}}
    • created_by: {{user_id}}
    • webhookPassword: {{webhook_password}}

When a workflow reaches its expiry date, the workflow API calls this webhook by sending a POST request to the specified URL. Your system can then handle the expiration event as desired, such as archiving expired workflows or notifying users to renew them.

These use cases show how you can use webhooks to extend the functionality of the Workflow API by enabling real-time notifications and automatic responses to specific workflow events. By integrating these webhooks into your system, you can streamline workflow management and improve the user experience.


    Do you need further support?

      • Related Articles

      • CSC API

        Introduction Welcome to the CSC API from SIGN8! This guide is designed to help you integrate our CSC API seamlessly into your system. The CSC API can be used to create digital signatures on documents and data. It follows the standards set by the ...
      • Integration for your system

        Here you will find comprehensive information on our API solutions for digital signatures. As a leading provider, we offer two types of APIs that enable seamless integration and efficient workflows: Workflow API The Workflow API allows you to quickly ...
      • API Changelog

        September 2024 New Features Breaking Changes The date of the signature is now displayed in the signature screen of the QES. Bug Fixing August 2024 New Features Breaking Changes Bug Fixing July 2024 New Features Breaking Changes Bug Fixing June 2024 ...