API Specification

API functionality is provided by simple JSON structures. The API can be controlled by text tags embedded in the PDF or entirely through the command parameters.

The entire JSON string is Base64 encoded and supplied as a single parameter. The JSON string contains objects with arrays of field types:

• file
• configuration
• signatures[]
• initials[]
• checkboxes[]
• radiobuttons[]
• textfields[]
• dates[]

API Command List

File Options

file: Used to specify HTTP or Filesystem for I/O.

Input

Key	Example Value	Type	Description
filesystem	c:\test.pdf	string	Absolute file path to PDF to open.
document_id	id123	string	Unique identifier for a document.
drive_id	id456	string	OneDrive only. Unique identifier for a user.
http_get	http://pdf_server.com/pdfs/test.pdf	string	Absolute URL to an HTTP server providing PDFs via GET.
ms_graph	json { "document_id": "012...", "user_email": "abc..." }	object literal	JSON object literal containing a document unique identifier and an ID for either OneDrive or SharePoint, depending on the platform being used.
user_email	john.doe@test.com	string	SharePoint only. Unique email for a given user.

---

Output

Key	Example Value	Type	Description
filesystem	c:\test_complete.pdf	string	Absolute file path to the PDF to be saved upon completion.
document_id	id123	string	Unique identifier for the document previously received.
drive_id	id456	string	OneDrive only. Unique identifier for the user who had previously requested the document.
http_post	http://pdf_server.com/pdfs/test.pdf	string	Absolute URL to an HTTP server receiving the PDF via POST (PDF as the body).
ms_graph	json { "document_id": "012...", "user_email": "abc..." }	object literal	JSON object literal containing the document’s unique identifier and the corresponding ID for either OneDrive or SharePoint, depending on the platform.
user_email	john.doe@test.com	string	SharePoint only. Unique email for the user who had previously received the document.

---

Authentication

Key	Example Value	Type	Description
pdf_user_password	pass123	string	User password for opening PDF.
http_user	user	string	HTTP Basic Authentication Username.
http_pass	pass456	string	HTTP Basic Authentication Password.
ms_graph_access_token	<JWT>	string	JWT for access tokens used to call an API.

---

Configuration

configuration: Used to configure the sign pro PDF user interface and behavior.

Key	Example Value	Type	Description
auto_delete_api_file	true	boolean	Option to delete the .signpro file when sign pro PDF exits after being started with the -apiFile switch.
auto_save	true	boolean	After signing all required signatures, the PDF is automatically saved, and sign pro PDF exits.
embed_fonts	true	boolean	Specify whether to embed fonts in the saved PDF, required for non-Latin fonts used in input fields.
error_handler_url	http://www.test.com:9090	string	Absolute URL to a server accepting error messages via POST.
fit_width	true	boolean	Zooms the document to fit in the display area.
process_text_tags	true	boolean	Specify whether embedded Text Tags should be processed. If true, Signatures and Initials provided by the API will be ignored.
show_annotate	true	boolean	Allow freehand annotation on the document.
show_document_pane	false	boolean	Option to display the document pane to the left of the document display area.
show_manual_signature	false	boolean	Allow manual placement of signature fields (i.e., no predefined fields are present and none are added via the API).
show_top_bar	false	boolean	Option to display the upper toolbar. When false, this also forces auto_save to true. Form filling and annotations are not accessible when the toolbar is not displayed.
show_bottom_bar	false	boolean	Option to display the lower toolbar.
tablet_display	true	boolean	If true, sign pro PDF will open on the first detected Wacom tablet display. Ensure the tablet is running at native resolution and 100% scaling for best results.
tablet_selection	Bottom	string	The full range of supported values: "left", "right", "top", "bottom", "first", and "last". The API value will override the config setting. Note: Should only be used for Citrix or RDP.

Signature

signature: Array of signatures to predefine in the document.

Key	Example Value	Type	Description
name	Signature_1	string	Name of the signature field (must be unique).
signer	Christopher Lea	string	Signatory Name.
reason	Agreement	string	Signatory Reason.
type	FSS	enum	Specify FSS, ISO, ISO2014 or ISO2021 Signature storage format. NB: ISO uses ISO 2014 and is interchangeable with ISO2014.
biometric	true	boolean	Specify true (default) or false to save Biometric metadata in the document.
required	false	boolean	Specify whether completion of this signature is required before the document can be completed.
location	...	Location	See Location Table below.
device	...	Device	See Device Table below.

---

Initial

initials: Array of initials to predefine in the document (small signatures).

Key	Example Value	Type	Description
name	initial_1	string	Name of the signature field (must be unique).
signer	Christopher Lea	string	Signatory Name.
reason	Agreement	string	Signatory Reason.
type	FSS	enum	Specify FSS, ISO, ISO2014 or ISO2021 Signature storage format. NB: ISO uses ISO 2014 and is interchangeable with ISO2014.
biometric	true	boolean	Specify true (default) or false to save Biometric metadata in the document.
required	false	boolean	Specify whether completion of this signature is required before the document can be completed.
location	...	Location	See Location Table below.

---

Text

textfields: Array of text fields to predefine in the document.

Key	Example Value	Type	Description
name	text_1	string	Name of the text field (must be unique).
value	Christopher Lea	string	Pre-filled default value of the text field.
location	...	Location	See Location Table below.

Date

dates: Array of date fields to predefine in the document.

Key	Example Value	Type	Description
name	date_1	string	Name of the date field (must be unique).
value	Christopher Lea	string	Pre-filled default value of the text field.
format	mm/dd/yy	string	Visual format for the Date field. The value must match this format. Accepted formats:

Accepted Date Formats:

• "m/d"
• "m/d/yy"
• "mm/dd/yy"
• "mm/dd/yyyy"
• "mm/yy"
• "d-mmm"
• "d-mmm-yy"
• "dd-mmm-yy"
• "dd-mmmm-yyyy"
• "yymm-dd"
• "mmm-yy"
• "mmmm-yy"
• "mmm d, yyyy"
• "mmmm d, yyyy"
• "m/d/yy h:MM tt"
• "m/d/yy HH:MM"

Key	Example Value	Type	Description
location	...	Location	See Location Table below.

---

Checkbox

checkboxes: Array of checkboxes to predefine in the document.

Key	Example Value	Type	Description
name	checkbox_1	string	Name of the checkbox field (must be unique).
value	true	string	"true" or "false" indicating whether the box should be checked by default.
location	...	Location	See Location Table below.

Radio Button

radiobuttons: Array of radio buttons to predefine in the document.

Key	Example Value	Type	Description
name	radio_1	string	Name of the button (must be unique).
value	true	string	"true" or "false" indicating whether the button should be checked by default. If more than one button in the same group is marked "true", the last one will be selected.
group	group_1	string	Name of the Radio Button group this button belongs to. All buttons must be part of a group, and a group must have at least 2 buttons.
location	...	Location	See Location Table below.

---

Location

location: Common to all field types.

Key	Example Value	Type	Description
Page	1:2:3, 1-7, 1:2:5-9	string	Defines which Page(s) the object should exist on. Can define ranges (e.g., "1-3") or individual pages (e.g., "1:3:5:7"). If Location is set but Page is not, the object will repeat on every page.
X	234	int	Horizontal coordinate for the object's origin, in default PDF units, from the left.
Y	22	int	Vertical coordinate for the object's origin, in default PDF units, from the bottom.
W	200	int	Width of the object, in default PDF units.
H	50	int	Height of the object, in default PDF units.

Device

device: Array of devices to configure selection.

Key	Example Value	Type	Description
selection_mode	Automatic	string	Defines the mode for device selection. Valid options are: Automatic, DefaultDevice & UserSelection.
default_device	DTU-1141B	string	List of preferred device names, in order of preference.

JSON API Example

{
  "file": {
    "input": {
      "filesystem": "C:\\Dev\\BitBucket\\sign-pro-windows-wpf-api\\SinglePage Quote.pdf",
      "http_get": null
    },
    "output": {
      "filesystem": "C:\\Dev\\BitBucket\\sign-pro-windows-wpf-api\\SinglePage Quote_complete.pdf",
      "http_post": null
    },
    "authentication": {
      "pdf_user_password": "pass",
      "http_user": null,
      "http_password": null
    }
  },
  "configuration": {
    "show_annotate": false,
    "show_manual_signature": false,
    "error_handler_url": null,
    "process_text_tags": false
  },
  "device": {
    "selection_mode": "DefaultDevice",
    "show_manual_signature": "DTU-1141B"
  },
  "signatures": [
    {
      "name": "signature_1",
      "signer": "Chris",
      "reason": "fear",
      "type": "FSS",
      "biometric": true,
      "required": true,
      "location": {
        "Page": "1",
        "X": 123,
        "Y": 456,
        "W": 50,
        "H": 200
      },
      "device": {
        "selection_mode": "DefaultDevice",
        "default_device": "DTU-1141B"
      }
    },
    {
      "name": "s2",
      "signer": "C2",
      "reason": "f2",
      "type": "FSS",
      "biometric": true,
      "required": false,
      "location": {
        "Page": "1",
        "X": 175,
        "Y": 450,
        "W": 200,
        "H": 260
      }
    }
  ],
  "textfields": [
    {
      "name": "text1",
      "location": {
        "Page": "1",
        "X": 200,
        "Y": 600,
        "W": 150,
        "H": 44
      }
    },
    {
      "name": "text2",
      "value": "testing",
      "location": {
        "Page": "3",
        "X": 200,
        "Y": 600,
        "W": 150,
        "H": 44
      }
    }
  ],
  "initials": null
}

---

Text Tag Schema

When opened via the API, documents containing embedded Text Tags adhering to this schema will be processed, and the resulting objects will be placed according to their text position.

• TextTags must be enclosed with {{[[ and ]]}}.
• There must be no spaces between Keys.
• Tags can be as small as the PDF creator will allow or even the same color as the background, but they must exist in the main body of the document (not in annotations, sticky notes, form fields, etc.).

---

Defaults

All Tags have these features. Even if not defined below, the tag will support these values:

Key	Optional	Description	Example
Type	No	Defines the tag... each has a specific name.	Type=Signature
Name	No	The Name of the tag for IDML. For tags that occur on multiple pages, an integer is appended for each page it occurs on.	Ex. ApprovalSignature1,ApprovalSignature2,... Name=ApprovalSignature
Required	Yes	Boolean that states whether filling this field is required to finalize the document. 'true' or 'false' MUST be lowercase. Marking a Radio Button as required will mark the Group as required. Checkboxes cannot be marked required.	Type=Signature,Name=ApprovalSignature,Required=true
X	Yes	Define the horizontal location of the converted object. In PDF Units, Left Origin. If this is not set, the location of the TextTag itself will be used.	X=350
Y	Yes	Define the vertical location of the converted object. In PDF Units, Bottom Origin. If this is not set, the location of the TextTag itself will be used.	Y=150
Page	Yes	Defines which Page(s) the tag should exist on. Can define ranges e.g., "1-3" or individual pages e.g., "1:3:5:7". Page ranges must be enclosed in quotation marks " ". Ignored if Location is not set. If Location is set but Page is not, Object will repeat on every page.	Page="1:2:3", Page="1-7", Page="1:2:5-9"
W	Yes**	Defines the width of the control. **All tags have a default Height/Width if values aren't provided, but default values may not match existing document style & formatting so it's strongly encouraged to provide your own values.	W=250
H	Yes**	Defines the height of the control. **All tags have a default Height/Width if values aren't provided, but default values may not match existing document style & formatting so it's strongly encouraged to provide your own values.	H=72

Signature

The Signature tag places a signature.

Key	Optional	Description	Example
Type	No	Defines the Signature Tag	Type=Signature
Signer	Yes	Defines the name of the signer. Blank if not defined.	Type=Signature,Signer=Aaron Johnson
Reason	Yes	Defines the reason for signing. Blank if not defined.	Type=Signature,Reason=Approval
SigType	Yes	Defines the format of the stored Biometric data, FSS (default), ISO, ISO2014 or ISO2021. NB: ISO uses ISO 2014 and is interchangeable with ISO2014.	Type=Signature,Signer=Aaron Johnson,SigType=ISO
Biometric	Yes	True/False whether Biometric metadata should be included in the document.	Type=Signature,Signer=Aaron Johnson,Biometric=False

Here is a full example signature tag that might be inline in a PDF document:

{{[[Type=Signature,Name=ApprovalSignature,Signer=Aaron Johnson,Reason=Approval,Height=80,Width=250,SigType=FSS]]}}

Initial

Use the Initial tag to place an initials box. An Initials box is a small signature.

Key	Optional	Description	Example
Type	No	Defines the Initial Tag	Type=Initial
Signer	Yes	Defines the name of the signer. Blank if not defined.	Type=Initial,Signer=Aaron Johnson
Reason	Yes	Defines the reason for signing. Blank if not defined.	Type=Initial,Reason=Initials
SigType	Yes	Defines the format of the stored Biometric data, FSS (default), ISO, ISO2014 or ISO2021. NB: ISO uses ISO 2014 and is interchangeable with ISO2014.	Type=Signature,Signer=Aaron Johnson,SigType=ISO
Biometric	Yes	True/False whether Biometric metadata should be included in the document.	Type=Initial,Signer=Aaron Johnson,Biometric=False

Here is a full example initial tag, to insert initials boxes in each bottom left corner 1" in:

{{[[Type=Initial,Name=InitialsTest,Signer=Aaron Johnson,Reason=Approval,X=72,Y=72,Height=60,Width=60]]}}

Text

Key	Optional	Description	Example
Type	No	Defines the TextTag	Type=Text
Value	Yes	Populate the text field with a default text string.	Value=Chris

A full example can be: {{[[Type=Text,Name=FirstName,Value=Chris,Width=200,Height=50]]}}

Date

Key	Optional	Description	Example
Type	No	Defines the DateTag	Type=Date
Format	No	Define the date format to be displayed/tested. Same options as sign pro proper.	Format=mm/dd/yyyy
Value	Yes	Populate the Date field with a default text string (must match the format).	Value=12/31/2019

A full example can be: {{[[Type=Date,Name=Birthday,Page=2,Height=50,Width=200,Value=12/31/2019,Format=mm/dd/yyyy]]}}

Checkbox

Key	Optional	Description	Example
Type	No	Defines the TextTag	Type=Checkbox
Value	Yes	Select the checkbox by default. Acceptable values are 'true' or 'false'.	Value=true

A full example can be: {{[[Type=Checkbox,Name=Primary,Value=true]]}}

Radio Button

Key	Optional	Description	Example
Type	No	Defines the TextTag	Type=Checkbox
Value	Yes	Select this button by default. Acceptable values are 'true' or 'false'. Only one button per group can be selected.	Value=True
Group	No	Define the group for this button. Groups can have no less than 2 buttons, and a Group must be defined.	Group=Sex

Full examples can be:

{{[[Type=RadioButton,Name=Male,Value=True,Page=2,Group=Sex,Width=50,Height=50,Y=200]]}}

or

{{[[Type=RadioButton,Name=Female,Page=2,Group=Sex,Width=50,Height=50,Y=260]]}}