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"
        }
    ]
}