---
updatedAt: 2025-09-16T01:03:45.000Z
agentTools:
  projectIndex: https://dev.proof.com/llms.txt
---

# Designations via API

Providing [designation](https://dev.proof.com/docs/document-tagging) 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](https://pdfa.org/resource/iso-32000-pdf/) (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](https://dev.proof.com/reference/create-business-transaction) endpoint:

```json
POST /transactions
{
  "signers": [
    {
      "email": "foobar@example.com",
      "external_id": "abc123
    }
  ],
	"draft": true
}
```

Then, call the [Add Document](https://dev.proof.com/reference/add-business-documents) 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](https://dev.proof.com/docs/api-data#the-signing_designations-array) for more info.

## Adding Designations for Notaries

To apply a designation for a notary via API, simply call the [Add Document](https://dev.proof.com/reference/add-business-documents) 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.

## 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.

```json json
"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).