# Optional: Place signatures

## Positioning with text anchors 

You can define where signatures and initials will be placed in **PDF or DOCX documents** using **anchor texts**.\
Just insert an identifier, such as `"<<signer1>>"`, in the document, and the platform will **automatically position the signature or initial exactly where this text appears**.

**Tip:** use `<< >>` to avoid conflicts with common words in the document.

**Fields**

* **`signature_placement`**: defines the location of the **signature** using an anchor text.\
  Example: `"signature_placement": "<<signer1>>"`
* **`rubrica_placement`**: defines the location of the **initial** using an anchor text.\
  Example: `"rubrica_placement": "<<signer1Rubrica>>"`

If the text appears more than once, the signature or initial will be **placed in all locations**.

**Where to use anchors**\
Anchors can be configured in the following endpoints:

[Create document via Upload](https://docs.zapsign.com.br/english/documentos/criar-documento)

[Create document via Template](https://docs.zapsign.com.br/english/documentos/criar-documento-via-modelo)

[Add signer](https://docs.zapsign.com.br/english/signatarios/adicionar-signatario)

[Update signer](https://docs.zapsign.com.br/english/signatarios/atualizar-signatario)

## Positioning with coordinates in the position signatures endpoint

It is possible to define the exact position of each signature or initial using manual coordinates.

<mark style="color:green;">`POST`</mark> `https://api.zapsign.com.br/api/v1/docs/{{doc_token}}/place-signatures/`

#### Headers

<table><thead><tr><th width="202">Name</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>string</td><td><p>apiToken ahead of the "Bearer" text. </p><p>Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23</p></td></tr></tbody></table>

#### Request Body

<table><thead><tr><th>Name</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td>rubricas[type]</td><td>string</td><td>There are two types of rubrics possible, the "signature" or the "visto" (initials). Default: "signature".</td></tr><tr><td>rubricas[page]</td><td>integer</td><td>Page where the signature will be placed. Starts at 0.</td></tr><tr><td>rubricas[relative_size_x]</td><td>number</td><td>(Explained below)</td></tr><tr><td>rubricas[relative_size_y]</td><td>number</td><td>(Explained below)</td></tr><tr><td>rubricas[relative_position_bottom]</td><td>number</td><td>(Explained below)</td></tr><tr><td>rubricas[relative_position_left]</td><td>number</td><td>(Explained below)</td></tr><tr><td>rubricas[signer_token]</td><td>string</td><td>Signer token of the signature that will be placed</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Placement completed successfully." %}

{% endtab %}
{% endtabs %}

### Request

{% embed url="<https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-c5d8b072-37cf-4e5d-a4b7-3b905f1e1140?ctx=documentation>" %}

### How does positioning via API work?

How does ZapSign calculate where these signatures should be placed? According to the calculations below:

![We have the x-axis and y-axis starting at the lower left corner of each page.](https://1401277393-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4noMoX5ZGb2-RhWjjf%2F-MIvKPkSUymokCFcqr2j%2F-MIvPl0UUr3g15v1BeUB%2Fimage.png?alt=media\&token=374d3770-d179-4cdf-8475-85a278429ce1)

The position shown above, of the signature of "Fulano Silveira" in the right side of the document, would correspond to the JSON:

```javascript
    {
        "page": 0, //1st document page
        "relative_position_bottom": 42.50, //distance from 0 to 100 from the bottom edge of the page
        "relative_position_left": 65.71, //distance from 0 to 100 from the left edge of the page
        "relative_size_x": 19.55, //size from 0 to 100 of signature compared to page width 
        "relative_size_y": 9.42, //size from 0 to 100 of signature compared to page height
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg" //signer token of "Fulano Silveira"
    }
```

Below is a detailed explanation of each of the fields.

### **relative\_position\_left e relative\_position\_bottom:&#x20;*****Positioning the signature on the document***

It is necessary to take some care so that signatures are not left out of the document. For example, if relative\_position\_left is 80, relative\_size\_x must not be greater than 20 (totaling 100 which is the X axis). If this sum is greater than 100, the signature would be partly outside the document.

Mathematically speaking, your object must respect the following limits:\
0 <= relative\_size\_y <= 100\
0 <= relative\_size\_x <= 100\
0 <= relative\_position\_bottom <= 100\
0 <= relative\_position\_left <= 100

And also:\
0 <= (relative\_size\_y + relative\_position\_bottom) <= 100\
0 <= (relative\_size\_x + relative\_position\_left) <= 100

### **relative\_size\_x e relative\_size\_y:&#x20;*****Keeping the signature proportionate***

* **If your PDF is a vertical A4 sheet (most common),** it is recommended to always use relative\_size\_x: 19.55 and relative\_size\_y: 9.42, as in the example above. If you want to increase the subscription size, multiply them by the same number so that the ratio is maintained.
  * Note: if it is a rubric with type "visto", relative\_size\_x: 13.76 and relative\_size\_y: 9.42 are recommended

*

```
**If the PDF is a horizontal A4 sheet**, relative\_size\_x: 15.05 and relative\_size\_y: 12.13 are recommended.
```

```
* Note: if it is a rubric with type "visto", relative\_size\_x: 10.58 and relative\_size\_y: 12.13 is recommended
```

### page: *How to define the page where the signature will be placed*

The page parameter is equivalent to each page of the document, starting at 0. If you want to place the signature in the same place on all pages, you need to pass the object more than once. For example:

```javascript
{
	"rubricas":[
    {
        "page": 0, //1st document page
        "relative_position_bottom": 42.50, 
        "relative_position_left": 65.71, 
        "relative_size_x": 19.55, 
        "relative_size_y": 9.42, 
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
    },
    {
        "page": 1, //2nd document page
        "relative_position_bottom": 42.50, 
        "relative_position_left": 65.71, 
        "relative_size_x": 19.55, 
        "relative_size_y": 9.42, 
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
    }
  ]
}
```

### Frequently asked questions

* **How do I know if the placement of signatures worked?** A.: You will only know after the document is signed, directly checking the PDF. Validations must be done on your side.
* **If the positioning was done wrong, can I change it?** A.: To overwrite the placement of the previous signatures, just make a new POST for this route, and all previous placements will be deleted and replaced by the new ones.
* **How can I cancel placement of signatures?** A.: Just make a post with the rubrics object being an empty array. E.g.: {"rubricas":\[ ]}
* **Is the signed document updated whenever I change the placement of the signatures?** A.: No!!! The new placement will only be applied after a new signer signs the document. Thus, the document will not be updated every time you change the placement of signatures, but only when a signer signs.