Guides

Create a Task from Scratch

Suggest Edits

The Create a Task API allows for comprehensive task customization but its complexity may pose challenges for beginners. Therefore, this document provides explanations beyond the API documentation, including illustrations that compare parameters with their corresponding web functionalities.

Mapping with UI

In DottedSign, creating a task through the web interface includes multiple steps, each containing several configurable segments. Each segment correlates with different API parameters. The commonly used settings are organized in the following table for clarity. For guidance on using the web interface, please refer to our DottedSign Support for more detailed illustrations.

ParameterWeb Segment
base64_file, template_id​​​​file_mission_id[DottedSign API] Prepare Doc.png[DottedSign API] Multiple Docs.png
stages[].name and stages[].email[DottedSign API] Signers.png
stages[].field_settings[DottedSign API] Field Settings.png
stages[].field_settings[].options[DottedSign API] Field Setting Options.png
stages[].stage_setting[DottedSign API] Stage Setting.png
stages[].verify_methods[DottedSign API] Verify Method.png
task_setting[DottedSign API] Task Setting.png

🚧

Notice

The correlation between parameters and the interface is for reference only and may vary slightly with version updates.

Create with Multiple PDF Files

If users want to merge multiple PDF files to create a task, they must first initiate a FileMission using the Create a File Mission API. Subsequently, they can upload the PDF files through the upload link in the API response. The response is as follows:

{
    "data": {
        "file_mission_id": 9891,
        "status": "file_uploading",
        "upload_link": {
            "files": [
                {
                    "file_object_id": "DottedSignAPI_File_26c5bacf-bbec-4a9f-ad0c-deba775b7c4b",
                    "upload_link": "https://dotted-sign.s3-accelerate.amazonaws.com/xxxxx",
                    "extract_file_name": "doc 1"
                },
                {
                    "file_object_id": "DottedSignAPI_File_78aae962-f700-4dfa-85d7-733c46e96c02",
                    "upload_link": "https://dotted-sign.s3-accelerate.amazonaws.com/xxxxx",
                    "extract_file_name": "doc 2"
                }
            ]
        }
    }
}

🚧

Notice

The task involving multiple PDF files will be created asynchronously and sent to signers (if start is set to true) once the file merging is fully completed.

Mapping with Template Parameters

If users have already created templates on DottedSign, they can use the Get a Template API to retrieve template data for creating tasks.

👍

Benefits

Utilizing template parameters simplifies the setup process by reducing the complexity of configuring parameters from scratch and eliminates the need for users to calculate field coordinates.

ParametersTemplate Parameters
template_idTemplate ID
stagesdetails. Be aware that details includes owner information in the first item, resulting in the stage information starting after the details[0].
stages[i].namedetails[i+1].name
stages[i].emailThe template does not specify an email.
stages[i].field_settingsdetails[i+1].field_settings
stages[i].field_settings[j].optionsstages[i+1].field_settings[j].options. Be aware that field options of a template cannot specify signer-specific information, such as default, default_type, and zone. For more details, please refer to the API Reference.
stages[i].verify_methodsdetails[i+1].verify_methods. Be aware that verify methods of a template cannot specify signer-specific information, such as verify_source.
task_settingtemplate_setting

Examples

Minimal Usage

Creating a task fundamentally requires parameters including the task name, signer information, and signing fields. Each signing field must specify its field type and coordinates. For a more detailed explanation of field types and the approach to calculating coordinates, please refer to the FieldSetting section.

{
  "file_name": "My Task",
  "template_id": 1,
  "stages": [
    {
      "email": "[email protected]",
      "name": "John",
      "field_settings": [
        {
          "field_type": "signature",
          "page": 0,
          "coord": [100.0, 200.0, 300.0, 250.0],
          "options": {
            "force": true,
            "placeholder": "Your Signature"
          }
        },
      ]
    }
  ]
}

Full Configuration

Based on the critical parameters mentioned in the above Mapping with UI section, all parameters can be referenced in the following example.

{
  "file_name": "File Name",
  "template_id": 1,
  "stages": [
    {
      "email": "[email protected]",
      "name": "John",
      "field_settings": [
        {
          "field_type": "signature",
          "page": 0,
          "coord": [100.0, 200.0, 300.0, 250.0],
          "options": {
            "force": true,
            "placeholder": "Your Signature"
          },
        },
        {
          "field_type": "textfield",
          "page": 0,
          "coord": [400.0, 200.0, 600.0, 250.0],
          "options": {
            "force": true,
            "placeholder": "Your Name",
            "read_only": true,
            "default": "John",
            "font_size": 20,
            "font_size_fixed": false,
            "alignment": "center",
            "alignment_fixed": false,
            "validation": "letters",
            "length": 500
          }
        },
        {
          "field_type": "datefield",
          "page": 0,
          "coord": [100.0, 300.0, 300.0, 350.0],
          "options": {
            "force": true,
            "placeholder": "Signing Date",
            "read_only": true,
            "default": "2020/02/20",
            "font_size": 20,
            "font_size_fixed": false,
            "alignment": "center",
            "alignment_fixed": false,
            "date_format": "yyyy/mm/dd",
            "date_setting": "no_limit",
            "zone": 8
          }
        }
      ],
      "attachment_settings": [
        {
          "attachment_id": "attachment_1",
          "file_name": "Identity Card",
          "force": true,
          "viewable_in_processing": true
        }
      ],
      "stage_setting": {
        "forward_enable": false,
        "decline_enable": false,
        "viewable_in_processing": true,
        "viewable_in_completed": true,
        "informable": false
      },
      "verify_methods": [
        {
          "verify_type": "email",
          "occasion": "sign"
        },
        {
          "verify_type": "sms",
          "verify_source": "+886123456789",
          "occasion": "sign"
        }
      ]
    }
  ],
  "task_setting": {
    "deadline": 1704067200,
    "forget_remind": true,
    "expire_remind": true,
    "remind_days_before_expire": 3,
    "receiver_lang": "en",
    "message": "Please sign the document.",
    "completed_message": "Thank you for signing the document.",
    "owner_informable": false,
    "cc_infos": [
      {
        "email": "[email protected]",
        "name": "Marry"
      }
    ]
  }
}

Updated 16 days ago