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:

JSON

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:

JSON

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:

JSON

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.

JSON

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.