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 environment: Set 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 documentation: Import 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 results: Review 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.

[PK] Primary key

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.