Packages

This section describes the following services related to document packages:

Retrieve a List of Packages

GET /packages

Description

Retrieves a list of document packages in an account.

Resource Information

HTTP Method GET
Resource Family packages
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 WVdECUMScUZGGGBGOlhVODdGNXFkR253SA==

Optional Query Parameters

query The set of packages you want to query. The following three options are available: (1) inbox (the query results are the set of packages that satisfy the value of the predefined parameter below); (2) drafts (the query results are the set of all your packages with the following statuses: DRAFT, DECLINED, EXPIRED, OPTED_OUT, OVERVIEW); (3) trashed (the query results are the set of all your trashed packages).
type Set type=TEMPLATE to return from the list of templates.
search Any text which is going to be used in conjunction with the searchtype,if provided. Limited to 100 search results at a time.
searchtype When this field is empty, a wild-card search will be performed using the package name and description for the search value, Otherwise, the allowable values of exact or exactname will make more restrictive searches.
predefined Predefined search criteria. The following five options are available: (1) awaitingSignature (the signer is the current session user, and the package status is SENT); (2) sent (the current session user is the package owner, and the package status is SENT); (3) completed (the package status is COMPLETED); (4) expiringSoon (the package will expire in expiringSoonDays days, and the package status is SENT); (5) all (the results will be the same as if you applied the previous four values sequentially, and then combined their search results). Note: The parameter expiringSoonDays is the number of days before a package expires that a warning will be sent to participants that the package will soon expire.
visibility

The visibility that will be used to search for templates (this parameter is used only for templates). The possible values are ACCOUNT (default) and SENDER.

lastUpdatedStartDate The date after which the package must have been last updated to be retrieved
lastUpdatedEndDate The date before which the package must have been last updated to be retrieved
from Specify the number of packages returned for the purposes of pagination. Note: A maximum of 100 packages can be returned.
to
sort The field according to which data will be sorted. Possible fields to sort by are: APPROVAL_ SIGNING_DATE, attributeValue, created, completed, updated, due, and name.
dir The direction according to which data will be sorted. Give the value asc for ascending, or desc for descending.

Example Request

GET https://sandbox.esignlive.com/api/packages

Retrieve Information about a Package

GET /packages/{packageId}

Description

Retrieve information about a single document package.

Resource Information

HTTP Method GET
Resource Family packages
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 WVdECUMScUZGGGBGOlhVODdGNXFkR253SA==

Path Parameters

packageId Unique identifier of a eSignLive package

The format of the package ID differs between versions 10.* and 11.* of eSignLive. For example, 5077da9e-0554-475d-8acc-b087007d0be6 is an acceptable v10 ID, while YU2HHW27zbJf2acHN5kmhEb96QQ= is an acceptable v11 ID. Your integration should not depend on the package ID's format. To ensure that this is the case: (1) create a package, and sign it in Sandbox; (2) if an error occurs, note that: (a) the package ID cannot be longer than 255 characters; (b) your integration should treat the package ID as an opaque string.

Example Request

GET https://sandbox.e-signlive.com/api/packages/84174f44-74f0-4e35-af45-6f1792df5972 

Retrieve the Signing Status of a Package

GET /packages/{packageId}/signingStatus

Description

Retrieve the signing status of a package.

Resource Information

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

Path Parameters

packageId Unique identifier of a eSignLive package

Optional Query Parameters

signer Unique ID of a signer of the package
document Unique ID of a document in the package

Example Request

GET https://sandbox.e-signlive.com/api/packages/84174f44-74f0-4e35-af45-6f1792df5972/signingStatus

Request Payload

{
   "document"="80f36f8dd7e2dea9"
}

Response Payload

If a package has been completed, the Response Payload is the following:

{
  "status": "COMPLETED"
}

If a package has been deleted, the Response Payload is the following (any Optional Query Parameter is ignored):

{
  "status": "DELETED"
}

If a package has not been completed or deleted, the Response Payload is one the following, depending on the status of the submitted Optional Query Parameter (signer or document). The Response Payload will reflect the signing status of the signer or document.

{
  "status": "SIGNING_PENDING"
}
{
  "status": "SIGNING_COMPLETED"
}

Retrieve an Overview of Packages

GET /packages/overview

Description

Retrieve the number of packages in each possible state.

Resource Information

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

Path Parameters

No path parameters are required.

Optional Query Parameters

startDate The date after which entries must have been updated in order to be retrieved
endDate The date before which entries must have been updated in order to be retrieved

Example Request

GET https://sandbox.esignlive.com/api/packages/overview

Response Payload

{
	"transactions": 5,
	"require_my_signature": 0,
	"waiting_on_others": 0,
	"about_to_expire": 0,
	"expired": 0,
	"completed": 2,
	"draft": 3,
	"cancelled": 0,
	"in_progress": 0
}

Retrieve Evidence Summary

GET /packages/{packageId}/evidence/summary

Description

Retrieve Evidence Summary information about a single document package.

Resource Information

HTTP MethodGET
Resource Familypackages
AuthenticationAuthentication Tokens
Content-typeapplication/json
Acceptapplication/pdf

Authentication

Either a Cookie header or an Authorization header is required.

CookieESIGNLIVE_SESSION_ID=108259418ff689fc
AuthorizationBasic WVdECUMScUZGGGBGOlhVODdGNXFkR253SA==

Path Parameters

packageIdUnique identifier of an eSignLive package

Example Request

GET https://sandbox.e-signlive.com/api/packages/84174f44-74f0-4e35-af45-6f1792df5972/evidence/summary 

Response Payload

[application/pdf]

Create a Package

POST /packages

Description

Creates a new document package from scratch. Note that Signing Ceremony Settings can be configured when you create or modify a package.

If you want eSignLive to vault a mortgage e-Note for a package, see Package Settings for Mortgages.

Resource Information

HTTP MethodPOST
Resource Familypackages
AuthenticationAuthentication Tokens
Content-typeapplication/json
Acceptapplication/json

Example Request

POST https://sandbox.e-signlive.com/api/packages/

Request Payload

{
   "name": "My Package",
   "type":"PACKAGE",
   "language":"en",
   "emailMessage":"",
   "description":"New Package",
   "autocomplete":true
}

Response Payload

{
    "id": "75b125e1-ece3-481e-b8a6-3c2ae39d310a"
}

Create a Package on Behalf of Another User

POST /packages

Description

You can create a package (or template ) on behalf of another user in your account. When you do this, you should specify that user manually, as this will prevent the creator of the package (or template ) from being added to the package (or template) as a signer.

You can set the visibility element to either ACCOUNT or SENDER, depending on if you want the new package to be visible account-wide, or visible just to the sender. The default setting is ACCOUNT.

The visibility element applies only to the creation of templates.

JSON Sample

{
   "type":"PACKAGE",
   "sender":{
      "lastName":"Smith",
      "firstName":"Bob",
      "email":"bobsmith@email.com"
   },
   "settings":{
      "ceremony":{
         "inPerson":false
      }
   },
   "name":"Package with sender",
   "visibility":"ACCOUNT",
   "language":"en",
   "emailMessage":"",
   "description":"Package with sender",
   "autocomplete":true
}

Create a Package with Document Binaries

POST /packages

Description

Creates a new package, together with document binaries. You can add as many files to the package as you want. Just ensure that the payload specifies the documents in the order in which they were added. Signing Ceremony Settings can be configured when you create or modify a package.

Resource Information

HTTP MethodPOST
Resource Familypackages
AuthenticationAuthentication Tokens
Content Typemultipart/form-data
Acceptapplication/json

Example Request

POST https://sandbox.e-signlive.com/api/packages/

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="Unsigned Document.doc"
Content-Type: application/msword

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
   "documents":[
      {
         "name":"Document Package 01"
      }
   ]
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

{
    "id": "4d09f2a8-4f0d-477b-8735-4b42ecf5ed0a"
}

Create an Accessible Package

POST /packages

Description

Creates an "accessible" package with document binaries. Blind and visually impaired signers will be able to review and sign the documents in this package.

The package' documents must be suitably tagged PDFs. To learn how to create them , see Accessibility Support. If the PDFs are not tagged, your request will not succeed.

This section describes how to create an accessible package with attached documents. If you wish, you can create an accessible package without any documents, then add the documents later.

Resource Information

HTTP MethodPOST
Resource Familypackages
AuthenticationAuthentication Tokens
Content Typemultipart/form-data
Acceptapplication/json

Example Request

POST https://sandbox.e-signlive.com/api/packages/

Request Payload

The Request Payload must: (1) specify fields and signatures using the same types as those given to the fields and signatures inside the package's tagged PDFs; (2) specify fields and signatures using the same names and IDs as those given to the names of the fields and signatures inside the package's tagged PDFs; (3) specify each approval's name and ID using the same name and ID of the associated signature; (4) set the extract flag to true for all relevant documents and fields.

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="Unsigned Document.doc"
Content-Type: application/msword

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"

{
  "settings": {
    "ceremony": {
      "ada": true
    }
  },
  "type": "PACKAGE",
  "language": "en",
  "name": "<Package Name>",
  "documents": [
    {
      "approvals": [
        {
          "role": "Customer",
          "name": "CustomerSignature",
          "id": "CustomerSignature",
          "fields": [
            {
              "name": "APR",
              "id": "APR",

              "extract": true,
              "type": "INPUT",
              "subtype": "TEXTFIELD"
            },
            {
              "name": "CustomerSignature",
              "id": "CustomerSignature",
              "extract": true,
              "type": "SIGNATURE",
              "subtype": "FULLNAME"
            }
          ]
        },
        {
          "role": "Customer",
          "name": "Agent",
          "id": "Agent",
          "fields": [
            {
              "name": "Agent",
              "id": "Agent",
              "extract": true,
              "type": "SIGNATURE",
              "subtype": "FULLNAME"
            }
          ]
        }
      ],
      "extract": true,
      "index": 0,
      "name": "Doc 1"
    }
  ],
  "roles": [
    {
      "type": "SIGNER",
      "id": "Customer",
      "signers": [
        {
          "signature": null,
          "firstName": "role",
          "lastName": "one",
          "email": "<email address>",
          "id": "Customer"
        }
      ],
      "name": "Customer"
    }
  ]
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

{
    "id": "4d09f2a8-4f0d-477b-8735-4b42ecf5ed0a"
}

Error Responses

The following error is created if you try to upload a PDF that is not tagged:

{
    "messageKey": "error.validation.ada.notTaggedDocument",
    "message": "Documents uploaded to accessible transactions must be accessibility enabled.",
    "code": 400,
    "name": "Validation Error"
}

The following error is created if you try to upload a PDF whose tags are not structured correctly:

{
    "messageKey": "error.validation.ada.documentNotTaggedProperly",
    "message": "Documents uploaded to accessible transactions must be tagged properly.",
    "code": 400,
    "name": "Validation Error"
}

The following error is created if you try to change the ada flag for a package that already contains documents. This error therefore occurs not when you create a package, but only when you update a package.

{
    "messageKey": "error.validation.ada.documentsExist",
    "message": "The ADA flag cannot be updated once documents are uploaded",
    "code": 400,
    "name": "Validation Error"
}

Clone a Package or Template

POST /packages/{packageId}/clone

Description

Create a package or a template from an existing package or template. Signing Ceremony Settings can be configured when you create or modify a package.

Resource Information

HTTP MethodPOST
Resource Familypackages
AuthenticationAuthentication Tokens
Content-typeapplication/json
Acceptapplication/json

Path Parameters

packageIdUnique ID of the eSignLive template to be cloned

Example Request

POST https://sandbox.e-signlive.com/api/packages/47132ca5-3687-4873-8ede-cc36eb93371d/clone

Request Payload

{
  "name":"Template1",
  "description":"",
  "emailMessage":"",
  "autocomplete":true,
  "settings": {
    "ceremony": {
      "inPerson":false
    }
  },
  "type":"PACKAGE",
  "due":null,
  "language":"en"
}

Response Payload

{
  "id": "3506c496-7b56-4fb5-9f9c-88bce25df1c2"
}

Bulk Send

POST /packages/{templateId}/bulk_send

Description

Create and distribute multiple transactions with minimum effort via Bulk Send. Bulk Send takes a two-part form/multipart request body (the payload, and the file).

Resource Information

HTTP MethodPOST
Resource Familypackages
AuthenticationAuthentication Tokens
Content Typemultipart/form-data
Accepttext/html

Example Request

POST https://sandbox.e-signlive.com/api/packages/{bulkSendableTemplateId}/bulk_send

Request Payload

{
    "name": "My custom package name",
    "description": "My custom package description" 
}

Request File

A CSV file with properly formatted Headers and Values.

Example Successful Response

{
    "id": "UID of the created bulk-send batch" 
}

Example Error Response

[
    {
        "messageKey": "Message key of the error",
        "rowNumber": "# of the CSV row where error occurred",
        "columnName": "Name of the column where error occurred",
        "roleName": "Name of the 'role-block' where error occurred" 
    },
    {
        "messageKey": "... additional errors (LIMITED TO 20 ERRORS)",
        "rowNumber": "...",
        "columnName": "...",
        "roleName": "..." 
    }
]    

Update a Package's Information

PUT /packages/{packageId}

Description

Update the information about a document package. Note that Signing Ceremony Settings can be configured when you create or modify a package.

Resource Information

HTTP MethodPUT
Resource Familypackages
AuthenticationAuthentication Tokens
Content-typeapplication/json
Acceptapplication/json

Path Parameters

packageIdThe unique packageId of the document package you want to modify.

Example Request

PUT https://sandbox.e-signlive.com/api/packages/75b125e1-ece3-481e-b8a6-3c2ae39d310a

Request Payload

{
   "name": "My Document"
}

Response Payload

no content

Delete a Package

DELETE /packages/{packageId}

Description

Delete a document package.

Resource Information

HTTP MethodDELETE
Resource Familypackages
AuthenticationAuthentication Tokens
Content-typeapplication/json
Acceptapplication/json

Path Parameters

packageIdUnique ID of a eSignLive package

Example Request

DELETE https://sandbox.e-signlive.com/api/packages/75b125e1-ece3-481e-b8a6-3c2ae39d310a

Response Payload

no content