Managing Signers' Attachments

Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to add a recipient with an attachment requirement.

HTTP Request

POST /api/cs-packages/{packageId}/roles

JS

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer access_token

JS

Request Payload

{
  "id": "client",
  "type": "SIGNER",
  "index": 1,
  "attachmentRequirements": [
    {
      "description": "Please upload a scanned copy of your driver's license.",
      "required": true,
      "id": "lD6p5QnWk905",
      "status": "INCOMPLETE",
      "comment": "",
      "name": "Driver's license"
    }
  ],
  "signers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com"
    }
  ],
  "name": "client"
}

JS

For a complete description of each field, see the Request Payload Table below.

Response Payload

{
    "id": "client",
    "data": null,
    "emailMessage": null,
    "attachmentRequirements": [
        {
            "status": "INCOMPLETE",
            "description": "Please upload a scanned copy of your driver's license.",
            "required": true,
            "id": "1JMGfs9xRDoD",
            "comment": "",
            "name": "Driver's license",
            "data": null
        }
    ],
    "locked": false,
    "reassign": false,
    "specialTypes": [],
    "index": 1,
    "type": "SIGNER",
    "signers": [
        {
            "group": null,
            "language": "en",
            "signature": null,
            "id": "fe666c24-c18d-4d93-bbb7-2b1a6ce8332e",
            "auth": {
                "scheme": "NONE",
                "challenges": []
            },
            "data": null,
            "title": "",
            "external": null,
            "updated": "2017-10-19T18:18:37Z",
            "company": "",
            "email": "john.smith@example.com",
            "firstName": "John",
            "lastName": "Smith",
            "phone": "",
            "professionalIdentityFields": [],
            "userCustomFields": [],
            "knowledgeBasedAuthentication": null,
            "delivery": {
                "provider": false,
                "email": false,
                "download": false
            },
            "address": null,
            "created": "2017-10-19T18:18:37Z",
            "name": "",
            "specialTypes": []
        }
    ],
    "name": "client"
}

JS

Downloading Attachments

Attachments can be downloaded in the following ways:

As a single attachment. This requires the attachment id.
In a package that includes all attachments.
In a package that includes all attachments from a specified signer.

To download an individual attachment, you will need the package and attachment ID. The following code will do this:

HTTP Request

GET /api/cs-packages/{packageId}/attachment/{attachmentId}

JS

HTTP Headers

Accept: application/octet-stream
Content-Type: application/octet-stream
Authorization: Bearer access_token

JS

Response Payload

[document.pdf]

JS

You can also download all attachments as a zip file in a package. The following code will do this:

HTTP Request

GET /api/cs-packages/{packageId}/attachment/zip

JS

HTTP Headers

Accept: application/zip
Content-Type: application/zip
Authorization: Bearer access_token

JS

Response Payload

[document.zip]

JS

To download all attachments as a zip file for a particular signer, you will make your request to:

HTTP Request

GET /api/cs-packages/{packageId}/attachment/zip/{roleId}

JS

HTTP Headers

Accept: application/zip
Content-Type: application/zip
Authorization: Bearer access_token

JS

Request Payload

[document.zip]

JS

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can also include a small feedback message explaining why the attachment was refused. The following code will do this:

HTTP Request

PUT /api/cs-packages/{packageId}/roles/{roleId}

JS

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer access_token

JS

Request Payload

{
  "attachmentRequirements": [
    {
      "id": "q66CYiDrxTU1",
      "status": "REJECTED",
      "comment": "Invalid copy."
    }
  ]
}

JS

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or reject it.

If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED. The following code will do this:

HTTP Request

PUT /api/cs-packages/{packageId}/

JS

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer access_token

JS

Request Payload

{
    "status" : "COMPLETED"
}

JS

JSON Property Table

Property	Type	Editable	Required	Default	Sample Values
id	string	Yes	No	n/a	`client`
type	string	Yes	No	SIGNER	`SIGNER` / `SENDER`
index	integer	Yes	No	0	`0/1/2`
name	string	Yes	No	n/a	`client`
attachmentRequirements
description	string	Yes	No	n/a	`Please upload a scanned copy of your driver's license`
required	boolean	Yes	No	false	`false/true`
id	string	Yes	No	n/a	`lD6p5QnWk905`
status	string	Yes	No	INCOMPLETE	`INCOMPLETE/COMPLETE/REJECTED`
comment	string	Yes	No	n/a	`wrong drivers license`
name	string	Yes	No	n/a	`Driver's license`
signers
firstName	string	Yes	No	n/a	`John`
lastName	string	Yes	No	n/a	`Smith`
email	string	Yes	No	n/a	`john.smith@example.com`