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. (Addins for more info)
"addins": [
{
"name": STRING,
"value": STRING
}
]Fields
Properties common to most or all fields
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.
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.
The id of the field, this id must be unique throughout the document.
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.
The required flag is set to true or false if the field is, respectively, mandatory or not.
The required flag is set to true or false if the field is, respectively, read only or not.
Defines at which step the field can be edited.(Constraint Rules)
The order for a field to be signed within its step.(Constraint Rules)
"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": [
{
"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.
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.