> For the complete documentation index, see [llms.txt](https://2sign-co-il.gitbook.io/2sign.co.il-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://2sign-co-il.gitbook.io/2sign.co.il-docs/tasks/defining-signature-fields.md).

# Defining Signature Fields

#### When to use this

Use this when you create a single task with `POST /api/V2/Tasks/CreateTask` and need to place or pre-fill fields before sending.

For the full task flow, see [Create a single Task](/2sign.co.il-docs/tasks/create-a-single-task.md).

For signature routines, see [Defining Signature Fields (Signature routine)](/2sign.co.il-docs/signature-routine-tasks/defining-signature-fields-signature-routine.md).

### Defining Signature Fields

You can define fields in several ways on the same endpoint.

Most integrations use either:

* `SignaturePositions` for exact placement
* `SearchWordForMarkingFieldsJson` for marker-based placement
* `SignaturePositionsStr` for simple pre-fill on existing fields

### Choose a method

| Method                           | Best for                   | Use when                                                                 |
| -------------------------------- | -------------------------- | ------------------------------------------------------------------------ |
| `SignaturePositions`             | Full control               | You need exact `X`/`Y` placement and field sizing                        |
| `SignaturePositionsSlimModel`    | Template-based updates     | Fields already exist on a template and you only need values and settings |
| `SignaturePositionsStr`          | Fast pre-fill              | You only need to set a few known field values                            |
| `SearchWordForMarkingSignature`  | One marker, signature only | Your document contains one marker for signature fields                   |
| `SearchWordForMarkingFieldsJson` | Multiple markers           | Your document contains different markers for different field types       |
| `SignaturesConstValues`          | Fixed positions            | You only need standard signature placement without coordinates           |

***

#### Method 1 - Coordinates Array (`SignaturePositions`)

This is the most flexible option. Pass an array of field objects with exact position, size, and field settings.

```json
{
  "SignaturePositions": [
    {
      "X": 189.75,
      "Y": 66.86,
      "Width": 83.73,
      "Height": 25.30,
      "Page": 1,
      "SignaturePositionTypeId": 12,
      "SignaturePositionStageTypeId": 1,
      "SignaturePositionFieldType": 1,
      "PositionTextContent": "Israel Israeli"
    }
  ]
}
```

Use this when:

* the document layout changes often
* you need exact field placement
* you need sender-side pre-fill values

**Key fields**

| Field                          | Type   | Description                                                       |
| ------------------------------ | ------ | ----------------------------------------------------------------- |
| `X` / `Y`                      | float  | Position on the page                                              |
| `Width` / `Height`             | float  | Size of the field                                                 |
| `Page`                         | int    | Page number                                                       |
| `SignaturePositionTypeId`      | int    | Field type ID                                                     |
| `SignaturePositionStageTypeId` | int    | Who fills this field: `0` required signer, `1` sender, `2` signer |
| `SignaturePositionFieldType`   | int    | `0` signature, `1` text, `2` checkbox, `3` dropdown, `4` date     |
| `PositionTextContent`          | string | Pre-fill a value before sending to client                         |
| `CheckBoxSelected`             | bool   | Default state for checkbox fields                                 |

{% hint style="info" %}
`SignaturePositionTypeId` identifies the field. `SignaturePositionFieldType` defines the input type, such as signature, text, checkbox, dropdown, or date.
{% endhint %}

{% hint style="info" %}
To reuse field positions from a template, call a template lookup endpoint, copy `SignaturePositions`, and update only the values you need. See [Get tamplates info](/2sign.co.il-docs/templates/get-tamplates-info.md).
{% endhint %}

***

#### Method 2 - Slim Model (`SignaturePositionsSlimModel`)

A structured list for template-based field updates. It supports descriptions, required state, and checkbox configuration without sending full coordinates.

You must send this together with `TemplateId`.

```json
{
  "SignaturePositionsSlimModel": [
    {
      "SignaturePositionTypeId": 1,
      "PositionTextContent": "Sample Text",
      "CheckBoxSelected": false,
      "Description": "Field description",
      "Required": true
    }
  ]
}
```

Use this when:

* the fields already exist on a template
* you need to pre-fill values
* you need to set field descriptions or required state

| Field                     | Type   | Description                                     |
| ------------------------- | ------ | ----------------------------------------------- |
| `SignaturePositionTypeId` | int    | Field type ID                                   |
| `PositionTextContent`     | string | Pre-filled value                                |
| `CheckBoxSelected`        | bool   | Default checkbox state                          |
| `Description`             | string | Label or description shown on the field         |
| `Required`                | bool   | Whether the field must be filled before signing |

{% hint style="warning" %}
This method is template-based. It does not place new fields on an uploaded file by coordinates.
{% endhint %}

***

#### Method 3 - Field String (`SignaturePositionsStr`)

A lightweight string format for pre-filling field values without building a full array.

Format: `"FieldTypeId-Value|FieldTypeId-Value"`

```json
{
  "SignaturePositionsStr": "4-client@example.com|6-Israel Israeli"
}
```

In this example, field type `4` is set to the email address, and field type `6` is set to the full name.

{% hint style="info" %}
Use this when fields already exist and you only need to pre-fill a few known values.
{% endhint %}

{% hint style="warning" %}
This method does not control position or size.
{% endhint %}

***

#### Method 4 - ASCII Marker (`SearchWordForMarkingSignature`)

Place a rare marker character on the document. Pass that character in the request, and the system places a signature field everywhere it finds it.

```json
{
  "SearchWordForMarkingSignature": "§"
}
```

Supports **signature fields only**.

Use this when:

* the document is generated outside the platform
* you want placement without coordinates
* one marker type is enough

***

#### Method 5 - ASCII Marker with Field Type Mapping (`SearchWordForMarkingFieldsJson`)

An extension of Method 4. It supports **multiple characters**, each mapped to a different field type.

Pass a JSON string where each entry defines a character and the field type it should create.

```json
{
  "SearchWordForMarkingFieldsJson": "[{ \"fieldSignaturePositionType\": \"1\", \"fieldSearchChar\": \"&\" }, {\"fieldSignaturePositionType\": \"6\", \"fieldSearchChar\": \"$\" }]"
}
```

| Field                        | Type   | Description                           |
| ---------------------------- | ------ | ------------------------------------- |
| `fieldSignaturePositionType` | string | Field type ID (see Generic Field IDs) |
| `fieldSearchChar`            | string | The character placed on the document  |

In this example, every `&` on the document becomes a signature field, and every `$` becomes a full name field.

{% hint style="warning" %}
Use rare characters that would not naturally appear in document text. Avoid `@`, `!`, `%`, or other common characters - any match in the document content will be treated as a field position.
{% endhint %}

{% hint style="info" %}
Unlike `SearchWordForMarkingSignature`, this method supports any field type.
{% endhint %}

{% hint style="info" %}
`fieldSignaturePositionType` identifies which field should be created for each marker.
{% endhint %}

***

#### Method 6 - Predefined Character Mapping *(Account Configuration)*

A subscription-level setting configured by 2Sign technical support. Specific characters are mapped to specific field types in the system. You place those characters in the document, and the system handles the rest.

To set this up, contact support at <dev@2sign.co.il> and provide the character-to-field mapping you need.

> 💡 **Tip** - This works well when your team generates documents programmatically and wants a zero-configuration request body.

***

#### Method 7 - Fixed Position Constants (`SignaturesConstValues`)

Place signatures at standard page positions without coordinates.

Format: `"page-position|page-position"`

#### Format

```
page-position|page-position
```

#### Meaning

```json
{
  "SignaturesConstValues": "1-1|2-3"
}
```

Position values:

| Value | Position      |
| ----- | ------------- |
| `1`   | Top Left      |
| `2`   | Top Center    |
| `3`   | Top Right     |
| `4`   | Middle Left   |
| `5`   | Middle Center |
| `6`   | Middle Right  |
| `7`   | Bottom Left   |
| `8`   | Bottom Center |
| `9`   | Bottom Right  |

* Invalid values are ignored silently
* This method **does not accept X/Y coordinates**
* Position values are mapped internally to fixed layout coordinates
* Multiple fields on the same page are supported

***

### Common pitfalls

* Use `SignaturePositions` when you need exact placement. Do not use `SignaturePositionsStr` for positioning.
* Use rare marker characters. Any accidental match in the document becomes a field.
* If you already use a template, reusing its `SignaturePositions` is usually faster than rebuilding positions manually.

***

The following table lists the available field types and their corresponding IDs:

* **1**: Signature
* **2**: Signing Date (auto)
* **3**: ID
* **4**: Email
* **5**: Free Text
* **6**: Client Name
* **8**: First Name
* **9**: Last Name
* **10**: Telephone Number
* **11**: Mobile Phone Number
* **12**: Full Name
* **13**: Full Address
* **14**: City
* **18**: Business Name
* **19**: Occupation Type
* **20**: Supplier
* **21**: Position
* **22**: Serial Number
* **25**: Unique ID
* **52**: Year of Birth
* **55**: Email Address


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://2sign-co-il.gitbook.io/2sign.co.il-docs/tasks/defining-signature-fields.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.