Documents

This section describes the following services that pertain to documents:

Retrieve a Single Document

GET /packages/{packageId}/documents/{documentId}

Description

Use to retrieve all information related to a given document, including id, name, description, presentation index, any associated data elements, approvals and fields. For information on how to retrieve the document itself, see Retrieve a PDF Document .

Resource Information

HTTP Method GET
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package
documentId Unique identifier of a eSignLive document

Example Request

GET https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents/e26835e526836eb8

Response Payload

Retrieve a PDF Document

GET /packages/{packageId}/documents/{documentId}/pdf

Description

Use to retrieve a specific document. This function always returns the PDF version of the document, even if the document was originally submitted in a different format. For information on how to retrieve information for a specific document see Retrieve a Single Document .

Resource Information

HTTP Method GET
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/pdf

Path Parameters

packageId Unique identifier of a eSignLive package
documentId Unique identifier of a eSignLive document

Optional Query Parameters

flatten

Flag that determines if a document will be flattened, no matter who makes this API call or when they make it.

Valid values: true | false

Default value: false

Example: flatten=true

Example Request

GET https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents/e26835e526836eb8/pdf

Response Payload

[application/pdf]

Retrieve a Zip File of Documents

GET /packages/{packageId}/documents/zip

Description

Retrieve a zip file that contains documents.

Resource Information

HTTP Method GET
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/zip

Path Parameters

packageId Unique identifier of a eSignLive package

Optional Query Parameters

flatten

Flag that determines if a document will be flattened, no matter who makes this API call or when they make it.

Valid values: true | false

Default value: false

Example: flatten=true

Example Request

GET https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents/zip

Response Payload

[application/zip]

Response Payload

{
	"status": "",
	"description": "",
	"id": "590fe3a00a57a1365c7bfa01e6971e4afb00633d9b6a4fab",
	"signedHash": null,
	"signerVerificationToken": null,
	"approvals": [],
	"pages": [{
		"id": "",
		"height": 1030.0,
		"width": 796.0,
		"top": 0.0,
		"left": 0.0,
		"version": 0,
		"index": 0
	}],
	"external": null,
	"extract": false,
	"data": {
		"ese_document_texttag_extract_needed": "false"
	},
	"fields": [],
	"index": 1,
	"name": "Sample Document",
	"size": 15985
}

Add a Document to a Package via a Document Resource

POST /packages/{packageId}/documents

Description

Add a new document to an existing package by using a document resource.

The system supports a maximum of 16 MB per document (smaller documents yield better performance — we recommend under 5 MB per document). However, there is no limit to: (1) the number of documents in a transaction; (2) the total collective size of documents in a transaction.

Resource Information

HTTP Method POST
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json or text/html

Example Request

POST https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents

Request Payload

{ "name": "Sample Document", "external": {"id":"resource_id", "provider":"account"} }

The resource_id parameter references a document resource that must already have been added to your account by our Technical Support department. To contact Technical Support (sign.support@onespan.com; 1-855-MYESIGN).

Response Payload

no content

Upload a New Document through multipart/form-data

POST /packages/{packageId}/documents

Description

Upload a new document through multipart/form-data.

Each uploaded document requires a Minimal Request Payload that includes the name of the document being uploaded. The document name should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ".

Example of a Minimal Request Payload

{ "name": "Sample Document" }

When a document is uploaded to eSignLive, its Content-Type must be specified correctly for the document's file type. Supported file types and their Content-Type include the pairs in this table:

File Type Content-Type
pdf application/pdf
docs application/msword
doc application/msword
rtf application/rtf
odt application/vnd.oasis.opendocument.text
txt text/plain

Resource Information

HTTP Method POST
Resource Family documents
Authentication Authentication Tokens
Content Type multipart/form-data
Accept text/html

Example Request

POST https://sandbox.esignlive.com/api/packages/YoRGkkwLUrh55YrPS7JnwfDPJIY=/documents

Request Payload

-----------------------------7d159c1302d0y0
Content-Disposition: form-data; name="payload"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

{ "name": "Sample Docx Document" }
-----------------------------7d159c1302d0y0
Content-Disposition: form-data; name="file"; filename="1_page_docx.docx"
Content-Type: application/msword
Content-Transfer-Encoding: binary

<actual file content, not shown here>
-----------------------------7d159c1302d0y0--

Response Payload

Example Request for Uploading Multiple Files

POST https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents

Request Payload

------WebKitFormBoundarynsfmFU0kqNNXLVPr
Content-Disposition: form-data; name="files[]"; filename="Unsigned Document 01.pdf"
Content-Type: application/pdf
------WebKitFormBoundarynsfmFU0kqNNXLVPr
Content-Disposition: form-data; name="files[]"; filename="Unsigned Document 02.pdf"
Content-Type: application/pdf

------WebKitFormBoundarynsfmFU0kqNNXLVPr
Content-Disposition: form-data; name="files[]"; filename="Unsigned Document 03.pdf"
Content-Type: application/pdf

------WebKitFormBoundarynsfmFU0kqNNXLVPr--

Response Payload

Sign All Documents in a Package

POST /packages/{packageId}/documents/signed_documents

Description

Sign all documents in a package.

Resource Information

HTTP Method POST
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json or text/html

Example Request

POST https://sandbox.e-signlive.com/api/packages/a608fd84-6831-4533-b8ac-43aab4f004cf/documents/signed_documents

Request Payload

Response Payload

no content

Update a Single Document

PUT /packages/{packageId}/documents/{documentId}

Description

Update a single document.

Resource Information

HTTP Method PUT
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package
documentId Unique identifier of a eSignLive document

Example Request

PUT https://sandbox.e-signlive.com/api/packages/442a185e-f9ca-4776-8305-f9458e0c94bd/documents/1262be986618bb13

Request Payload

{
	"name":"New Document"
}

Response Payload

Apply a Layout to a Document

POST /packages/{packageId}/documents/{documentId}/layout

Description

Apply a layout to a document.

Resource Information

HTTP Method POST
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package
documentId Unique identifier of a eSignLive document

Required Query Parameters

layoutId Unique identifier of the layout. Alternative to layoutName. Only one of layoutId/layoutName can be set.

Optional Query Parameters

layoutName The layout name. Alternative to layoutId. Only one of layoutId/layoutName can be set.

Example Request

POST https://sandbox.e-signlive.com/api/packages/762b8991-a6fe-490c-89d1-1222a5bbb097/documents/3c2cba0bafe78a24/layout?layoutId=d2617054-5d26-403f-a17d-142c07c50d64

Response Payload

no content

Reorder the Documents in a Package

PUT /packages/{packageId}/documents

Description

Reorder the documents in a package.

Resource Information

HTTP Method PUT
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package

Example Request

PUT https://sandbox.e-signlive.com/api/packages/762b8991-a6fe-490c-89d1-1222a5bbb097/documents

Request Payload

[{
   "id":"default-consent",
   "index":0
 },
 {
   "id":"4fc1bea95a39e410",
   "index":1
 },
 {
   "id":"3c2cba0bafe78a24",
   "index":2
		}]

Response Payload

no content

Remove an Existing Document from a Package

DELETE /packages/{packageId}/documents/{documentId}

Description

Remove from a package an existing document (as identified by documentId.).

Resource Information

HTTP Method DELETE
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package
documentId Unique identifier of a eSignLive document

Example Request

DELETE https://sandbox.e-signlive.com/api/packages/442a185e-f9ca-4776-8305-f9458e0c94bd/documents/1262be986618bb13

Response Payload

no content

Remove Multiple Existing Documents from a Package

DELETE /packages/{packageId}/documents

Description

Remove from a package multiple existing documents (the Request Payload lists the documentIds of the documents to be removed).

Resource Information

HTTP Method DELETE
Resource Family documents
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Path Parameters

packageId Unique identifier of a eSignLive package

Example Request

DELETE https://sandbox.e-signlive.com/api/packages/442a185e-f9ca-4776-8305-f9458e0c94bd/documents

Request Payload

[
"1262be986618bb13",
"3c2cba0bafe78a24"
]

Response Payload

no content

Configure Document Visibility

POST /packages/{packageId}/documents/visibility

Description

By default, during a Signing Ceremony all recipients can view all documents in a package.

The Document Visibility feature provides greater flexibility by enabling integrators to configure which recipients can view specific documents in a package during a Signing Ceremony. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

This feature is disabled by default. It must be enabled for your account before you will be able to use it. For more on this, contact Technical Support (sign.support@onespan.com; 1-855-MYESIGN).

The request should be a Document Visibility object that contains a list of configurations. Each configuration must have: (1) the Document ID of a specific document; (2) a list of Role IDs of the recipients who can view the document.

Note that:

  • The Package Owner can always see all documents in the package, so it's not necessary to include their Role ID in the configurations.
  • Documents not in the Document Visibility object will retain their existing visibility configuration (if any).

A future release will enable Document Visibility to be customized via a User Interface, with no need for integration.

Resource Information

HTTP Method POST
Resource Family documents/visibility
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Authentication

Either a Cookie header or an Authorization header is required.

Cookie ESIGNLIVE_SESSION_ID=108259418ff689fc
Authorization Basic cGR1b25nOkJzYnAyeXNJQURnSA==

Path Parameters

packageId Unique identifier of a eSignLive package

Example Request

POST https://sandbox.e-signlive.com/api/packages/Wxay7KYs8lVHmGk_u0oPMqEsz5c=/documents/visibility

Request Payload

Response Payload

no content

Retrieve Document Visibility

GET /packages/{packageID}/documents/visibility

Description

Retrieves information about which recipients can view specific documents in a package during a Signing Ceremony.

The response is a Document Visibility object that contains a list of configurations. Each configuration has: (1) the Document ID of a specific document; (2) a list of Role IDs of the signers who can view the document.

Note that:

  • Documents not in the Document Visibility object are visible to all recipients.
  • The Package Owner can always see all documents in the package, regardless of its Document Visibility configuration.

Resource Information

HTTP Method GET
Resource Family documents/visibility
Authentication Authentication Tokens
Content-type application/json
Accept application/json

Authentication

Either a Cookie heard or an Authorization header is required.

Cookie ESIGNLIVE_SESSION_ID=108259418ff689fc
Authorization Basic cGR1b25nOkJzYnAyeXNJQURnSA==

Path Parameters

packageId Unique identifier of a eSignLive package

Example Request

GET https://sandbox.e-signlive.com/api/packages/Wxay7KYs8lVHmGk_u0oPMqEsz5c=/documents/visibility

Response Payload