Building a document create request

To create a document one must obviously send a create document request, the document will be edited (if requested) and then stored with an associated id. The document will then be accessible through the URL https://[host]/eSignServer/?session={id}.

Even though all examples will be in json format the xml based requests follow the same structure [https://[host]/eSignServer/services for the WSDL]

Request Structure

{
    "artifact": STRING,
    "template": STRING,
    "docOrientation": {
        "referenceCorner": STRING,
        "units": STRING
    },
    "radioGroups": [
        {
            "name": STRING,
            "label": STRING,
            "required": BOOLEAN,
            "readonly": BOOLEAN,
            "step": INTEGER,
            "sequence": INTEGER,
            "owner": {
                "owner": [
                    STRING
                ],
                "ownerType": STRING
            },
            "variables": [
                {
                    "name": STRING,
                    "value": STRING
                }
            ],
            "value": STRING,
            "radioFields": [
                {
                    "name": STRING,
                    "width": INTEGER,
                    "height": INTEGER,
                    "location": {
                        "absolute": {
                            "x": INTEGER,
                            "y": INTEGER,
                            "pages": [
                                INTEGER
                            ]
                        },
                        "relative": {
                            "offsetx": INTEGER,
                            "offsety": INTEGER,
                            "searchtext": STRING,
                            "pages": [
                                INTEGER
                            ]
                        }
                    }
                }
            ]
        }
    ],
    "checkboxFields": [
        {
            "name": STRING,
            "label": STRING,
            "required": BOOLEAN,
            "readonly": BOOLEAN,
            "step": INTEGER,
            "sequence": INTEGER,
            "owner": {
                "owner": [
                    STRING
                ],
                "ownerType": STRING
            },
            "variables": [
                {
                    "name": STRING,
                    "value": STRING
                }
            ],
            "width": INTEGER,
            "height": INTEGER,
            "location": {
                "absolute": {
                    "x": INTEGER,
                    "y": INTEGER,
                    "pages": [
                        INTEGER
                    ]
                },
                "relative": {
                    "offsetx": INTEGER,
                    "offsety": INTEGER,
                    "searchtext": STRING,
                    "pages": [
                        INTEGER
                    ]
                }
            },
            "value": BOOLEAN
        }
    ],
    "textFields": [
        {
            "name": STRING,
            "label": STRING,
            "required": BOOLEAN,
            "readonly": BOOLEAN,
            "step": INTEGER,
            "sequence": INTEGER,
            "owner": {
                "owner": [
                    STRING
                ],
                "ownerType": STRING
            },
            "variables": [
                {
                    "name": STRING,
                    "value": STRING
                }
            ],
            "width": INTEGER,
            "height": INTEGER,
            "location": {
                "absolute": {
                    "x": INTEGER,
                    "y": INTEGER,
                    "pages": [
                        INTEGER
                    ]
                },
                "relative": {
                    "offsetx": INTEGER,
                    "offsety": INTEGER,
                    "searchtext": STRING,
                    "pages": [
                        INTEGER
                    ]
                }
            },
            "value": STRING,
            "font": STRING,
            "fontSize": INTEGER
        }
    ],
    "signatureFields": [
        {
            "name": STRING,
            "label": STRING,
            "required": BOOLEAN,
            "readonly": BOOLEAN,
            "step": INTEGER,
            "sequence": INTEGER,
            "owner": {
                "owner": [
                    STRING
                ],
                "ownerType": STRING
            },
            "variables": [
                {
                    "name": STRING,
                    "value": STRING
                }
            ],
            "width": INTEGER,
            "height": INTEGER,
            "location": {
                "absolute": {
                    "x": INTEGER,
                    "y": INTEGER,
                    "pages": [
                        INTEGER
                    ]
                },
                "relative": {
                    "offsetx": INTEGER,
                    "offsety": INTEGER,
                    "searchtext": STRING,
                    "pages": [
                        INTEGER
                    ]
                }
            }
        }
    ],
    "images": [
        {
            "name": STRING,
            "label": STRING,
            "location": {
                "absolute": {
                    "x": INTEGER,
                    "y": INTEGER,
                    "pages": [
                        INTEGER
                    ]
                },
                "relative": {
                    "offsetx": INTEGER,
                    "offsety": INTEGER,
                    "searchtext": STRING,
                    "pages": [
                        INTEGER
                    ]
                }
            },
            "width": INTEGER,
            "height": INTEGER,
            "base64": STRING
        }
    ],
    "variables": [
        {
            "name": STRING,
            "value": STRING
        }
    ],
    "addins": [
        {
            "name": STRING,
            "value": STRING
        }
    ],
    "barcodes": [
        {
            "type": STRING,
            "width": INTEGER,
            "height": INTEGER,
            "location": {
                "x": INTEGER,
                "y": INTEGER,
                "pages": [
                    INTEGER
                ]
            },
            "variables": [
                {
                    "name": STRING,
                    "value": STRING
                }
            ]
        }
    ],
    "textBlocks": [
        {
            "width": INTEGER,
            "height": INTEGER,
            "location": {
                "absolute": {
                    "x": INTEGER,
                    "y": INTEGER,
                    "pages": [
                        INTEGER
                    ]
                },
                "relative": {
                    "offsetx": INTEGER,
                    "offsety": INTEGER,
                    "searchtext": STRING,
                    "pages": [
                        INTEGER
                    ]
                }
            },
            "value": STRING,
            "name": STRING,
            "font": STRING,
            "fontSize": INTEGER,
            "leading": INTEGER
        }
    ],
    "mode": STRING,
    "owner": {
        "owner": [
            STRING
        ],
        "ownerType": STRING
    }
}

Document

Artifact/Template

The property artifact is expected to hold a BASE64 encoded PDF file whereas template must refer to id of an existing PDF template. Both these fields provide the artifact source data to create the document.

Only one of these properties should be present in the request, they are mutually exclusive.

Document Orientation

The property docOrientation is an object in itself that will indicate the reference corner based on which every added field will be placed, and the length measure unit used to position each field.

"docOrientation": {
    "referenceCorner": STRING,
    "units": STRING
}

Where reference corner can be LEFTTOP, RIGHTTOP, RIGHTBOTTOM, LEFTBOTTOM. Coordinates units: PX, MM, INCHES, USERUNIT.

Owner

"owner": {
    "owner": [
        STRING
    ],
    "ownerType": STRING
}

The owner defines which users can edit the document. There are currently two owner types; the "USER" type which is cross compared with the current logged user’s username and the "ROLE" type which is cross compared with the current logged user’s role.

Mode

The mode can be set to either SIGN or TSA where the document will be signed or timestamped after creation. It can also be set to the default value *NONE*.

Variables

Variables are name/value pairs that are used to store custom information or to configure document behaviors within eSign.

"variables": [
    {
        "name": STRING,
        "value": STRING
    }
]

Also, variables are stored along with the contract and can be used for built-in behavior, or in custom developed addin. For more information on variables that affect the documents' behavior read document variables.

Addins

Allows for the setup of specific Addins for the document only. For example use a specific SESSION_AUTHENTICATION addin when accessing the document. (link: Addins for more info)

"addins": [
    {
        "name": STRING,
        "value": STRING
    }
]

Fields

One can introduce the following fields in a document:

Properties common to most or all fields

location

The location refers to where the fields are to be added in the document.

"location": {
    "absolute": {
        "x": INTEGER,
        "y": INTEGER,
        "pages": [
            INTEGER
        ]
    },
    "relative": {
        "offsetx": INTEGER,
        "offsety": INTEGER,
        "searchtext": STRING,
        "pages": [
            INTEGER
        ]
    }
}

An absolute location is literally what its name suggests, the x and y mean the field will be x,y 'units' away from the 'referenceCorner' defined in the docOrientation object in every page defined in the pages.

Absolute location

A relative location will search, in the indicated pages, for the string in the searchText and will place the given field in its position with an x,y offset.

Relative location
name

The id of the field, this id must be unique throughout the document.

label

The label is the friendly name of the field, this means that for user experience purposes this is the id show instead of the name property.

required

The required flag is set to true or false if the field is, respectively, mandatory or not.

readonly

The required flag is set to true or false if the field is, respectively, read only or not.

step

Defines at which step the field can be edited.(Constraint Rules)

sequence

The order for a field to be signed within its step.(Constraint Rules)

owner
"owner": {
    "owner": [
        STRING
    ],
    "ownerType": STRING
}

The owner defines which users can edit the field. There are currently two owner types; the "USER" type which is cross compared with the current logged user’s username and the "ROLE" type which is cross compared with the current logged user’s role.

variables
"variables": [
    {
        "name": STRING,
        "value": STRING
    }
]

Variables are custom entries that can be associated to the given fields and are defined by string,string name/value pairs. There are, nonetheless some reserved variables with specific names that will affect the field containing them (specified in the definition of each field). Also, variables are stored along with the contract and can be used for built-in behavior, or in custom developed addin.

width/height

The width and height of the field in 'units' away from it’s x,y coordinates in the direction ('referenceCorner') defined in the docOrientation object in every page defined in the pages.