Designations via API

Providing designation coordinates via API is a good solution if you have few document templates to manage, and the designations have predictable X/Y coordinates.

❗️

Only Available via Add Document endpoint

We do not support including signing designations via the Create Transaction endpoint at this time.

The X/Y Coordinate System

Proof's X/Y coordinate tagging is based on the ISO 32000 PDF standard. See section 8.3, Coordinate Systems in the free 2020 PDF Specification (account required for download).

The default unit is the "user space unit", which is 1/72nd of an inch in a standard PDF implementation. For tagging purposes, you can assume that the origin of this unit space is the bottom left of the page, with positive X/Y values moving up and to the right side of the page.

Adding Designations for Signers

To apply designations for a signer via API, first you must provide an external_id for the signer via the Create Transaction endpoint:

POST /transactions
{
  "signers": [
    {
      "email": "[email protected]",
      "external_id": "abc123
    }
  ],
	"draft": true
}

Then, call the Add Document endpoint and include the signing_designations parameter in your request:

POST /transactions/ot_xxxxxxx/documents
{
    "resource": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "requirement": "notarization",
    "signing_designations": [
        { 
            "signer_identifier": "abc123",
            "type": "dob",
            "page_number": 0,
            "x": 100,
            "y": 100,
            "height": 20,
            "width": 20,
            "hint": "Required to complete purchase"
        }
    ]
}

See the signing designation data model for more info.

Adding Designations for Notaries

To apply a designation for a notary via API, simply call the Add Document endpoint and include the signing_designations parameter in your request, and set the signer_identifier parameter to notary:

POST /transactions/ot_xxxxxxx/documents
{
    "resource": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "requirement": "notarization",
    "signing_designations": [
        { 
            "signer_identifier": "notary",
            "type": "dob",
            "page_number": 0,
            "x": 100,
            "y": 100,
            "height": 20,
            "width": 20,
            "hint": "Required to complete purchase"
        }
    ]
}

Adding Conditional Designations

Proof supports the ability to make designations dependent on completion of another designations. A common use case is making a text designation available to a signer if they select an optional checkmark.

Conditional designations are triggered using two parameters on the signing_designation object: primary_designation_identifier and conditional_on_primary.

To begin, set a value for primary_designation_identifier on the designation you will be using to trigger the conditional designation. This designation must be set to optional via the optional parameter. Next, define a new signing_designation object for the conditional designation. You can then use the value you set as the primary designation identifier for the conditional_on_primary parameter of this object.

POST /transactions/ot_xxxxxxx/documents
{
    "resource": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "requirement": "notarization",
    "signing_designations": [
        { 
            "signer_identifier": "testsigner1",
            "type": "checkmark",
            "page_number": 0,
            "x": 100,
            "y": 160,
            "height": 20,
            "width": 20,
            "hint": "check this to expose another designation!",
            "optional": true,
           	"primary_designation_identifier": "check_primary"
        },
        { 
            "signer_identifier": "testsigner1",
            "type": "free_text",
            "page_number": 0,
            "x": 300,
            "y": 160,
            "height": 40,
            "width": 100,
            "hint": "Add more details",
          	"conditional_on_primary": "check_primary"
        }
    ]
}

If the signer were to select the optional check mark in the example above they would then be required to fulfill the free text designation.

Adding Field Instructions

You may wish to provide detailed guidance to signers or notaries on how to complete a given field - Proof supports adding instructions to any designation added via X/Y coordinate or template.

Adding Field Instructions via API

Use the instruction parameter to add instructions for the signer or notary specific to a given designation.

"signing_designations": [
    {
      "signer_identifier": "testsigner1",
      "type": "free_text",
      "page_number": 0,
      "x": 100,
      "y": 350,
      "height": 20,
      "width": 300,
      "hint": "What is your address?",
      "optional": false,
      "instruction": "Provide a residential mailing address - PO boxes are not acceptable."
    }
  ]

When the assigned user hovers over the designation in the Proof signing experience, they will see a tooltip containing the text assigned in the instruction. Signers will only see signer instructions while notaries are able to see both notary and signer instructions. There is a 500 character limit on field instructions and only fields resulting in some text annotation are supported (e.g. checkboxes/radio buttons do not support field instructions).