Data Binding and Synchronization

In integration scenarios, tasks are often initiated or managed through triggers from third-party services. For example, using Pipedrive as an illustrative CRM system, the following scenarios could occur:

  • When a new Pipedrive deal is added, a task related to the transaction contract needs to be sent to the trader for signature.
  • When a Pipedrive deal is deleted, the corresponding task created in DottedSign should also be deleted.

Furthermore, changes in DottedSign tasks may require corresponding updates in the third-party service:

  • When all signers have completed signing, the Pipedrive deal should be updated to "Closed-Won".
  • When all signers have completed signing, the signed contract should be downloaded for archiving and attached to the Pipedrive deal.

Thus, it is crucial for third-party services to have bidirectional binding with DottedSign tasks, allowing applications to identify which deal corresponds to which DottedSign task.

Binding Strategies

Recording Task ID

Once a task is created, the DottedSign API returns a task_id. The application can then associate this task_id with third-party data (e.g. deal_id from Pipedrive) and record it in its database.

Using Metadata

Developers can also directly record third-party data on the task using metadata during creation, with both the Quick Create a Task and Create a Task APIs. This method eliminates the need for users to manually maintain this binding relationship.

{
  "file_name": "My Task",
  "template_id": 1,
  "stages": [
    {
      "email": "[email protected]",
      "name": "John",
      ...
    }
  ],
  "metadata": {
    "pipedrive_deal_id": 999
  },
  ...
}

Synchronization Strategies

Proactive Trigger

Once data in the third-party service is updated, the application might synchronize with the DottedSign task. If using the Recording Task ID binding strategy, operations on the DottedSign API can be carried out based on the mapped task_id, such as using the Void a task or the [Discard a Task] API.

If only the Using Metadata binding strategy is utilized, users must search for tasks containing specific metadata (e.g. pipedrive_deal_id=999) via the Get task list API and then carry out the appropriate actions using the DottedSign API.

Passive Updates by Polling

Developers can periodically retrieve tasks of interest using the Get task list API or the Get a Task API to obtain the latest status. By monitoring changes in parameters, corresponding actions can be taken, such as updating the Pipedrive deal when a task status changes to declined.

🚧

Be Aware of Rate Limits

Be mindful of the Rate Limit set by the DottedSign API to avoid reaching the usage cap, which could impact your application functionalities.

Passive Updates by Webhook

If developers have configured a webhook, they can receive events whenever there is activity in a task. These events include the action_name, the corresponding task_id, and the related metadata. Actions can be performed based on this data, such as triggering the Download the task API to archive the completed document after receiving a completed event.

{
  "resource_id": 999,
  "resource_type": "SignTask",
  "action_name": "completed",
  "event_datetime": "1704067200",
  "event_email": "[email protected]",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
  "task": {
    "task_id": 999,
    "metadata": {
      "pipedrive_deal_id": 999
    },
    ...
  }
}