> 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/signature-routine-tasks/defining-signature-fields-signature-routine.md).

# Defining Signature Fields (Signature routine)

Signature Routine tasks use the same field definition methods as Single Tasks, with three additional required fields on every signature position object:

| Field                          | Type | Description                                             |
| ------------------------------ | ---- | ------------------------------------------------------- |
| `ClientId`                     | int  | The specific signer this field belongs to               |
| `SignatureRoutineSignerNumber` | int  | Signing order (`1` = first to sign, `2` = second, etc.) |
| `IsSignatureRoutine`           | bool | Must be `true` on all fields                            |

For all other field options, see Defining Signature Fields - Single Task.

***

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

Each object in the array is assigned to a specific signer via `ClientId` and `SignatureRoutineSignerNumber`. A single document can have multiple signers, each with their own field.

```json
{
  "SignaturePositions": [
    {
      "X": 20,
      "Y": 100,
      "Width": 30,
      "Height": 20,
      "Page": 1,
      "SignaturePositionTypeId": 1,
      "SignaturePositionStageTypeId": 0,
      "SignaturePositionFieldType": 0,
      "IsMultipleOptionsCheckbox": false,
      "PositionTextContent": null,
      "CheckBoxSelected": false,
      "ClientId": 49728,
      "SignatureRoutineSignerNumber": 1,
      "IsSignatureRoutine": true
    },
    {
      "X": 20,
      "Y": 140,
      "Width": 30,
      "Height": 20,
      "Page": 1,
      "SignaturePositionTypeId": 1,
      "SignaturePositionStageTypeId": 0,
      "SignaturePositionFieldType": 0,
      "IsMultipleOptionsCheckbox": false,
      "PositionTextContent": null,
      "CheckBoxSelected": false,
      "ClientId": 49729,
      "SignatureRoutineSignerNumber": 2,
      "IsSignatureRoutine": true
    }
  ]
}
```

{% hint style="info" %}
Each signer must have at least one field with their `ClientId`. `SignatureRoutineSignerNumber` sets the signing order in a sequential routine — signer `1` signs first, then signer `2`, and so on.
{% endhint %}

***

#### Method 2 — ASCII Marker

Use this method when the PDF already contains marker characters instead of fixed coordinates.

The system scans the document for each `SearchCharSignature` value and creates the signer field where that marker appears.

Each object inside `SearchWordForSignatureRoutine` maps:

* one marker in the PDF
* one signer in the routine
* one signer order value

### Two supported signer modes

You can identify the signer in two ways:

1. by existing `ClientId`
2. by inline signer details with `ClientId: null`

#### Example 1 - Existing clients by `ClientId`

Use this when the signers already exist in your account.

The marker is linked to a saved client record through `ClientId`. You do not need to send `ClientPhones` or `ClientEmails` in the field object when the existing client record already identifies the signer.

```json
{
  "TaskSubject": "9909 Signature routine with ASCII search with client Id",
  "TaskGuid": "{{TaskGuid}}",
  "PdfGuid": "{{PdfGuid}}",
  "Language": 1,
  "LanguageMarked": "he",
  "IsSendOnCreation": true,
  "SignatureRoutine": true,
  "SignatureRoutineAsync": true,
  "GroupId": {{GroupId}},
  "SearchWordForSignatureRoutine": [
    {
      "ClientId": 686185,
      "SearchCharSignature": "###",
      "SignaturePositionFieldType": 1,
      "SignerNumberInRoutine": 1,
      "ClientPhones": null,
      "ClientEmails": null
    },
    {
      "ClientId": 569520,
      "SearchCharSignature": "@@@",
      "SignaturePositionFieldType": 1,
      "SignerNumberInRoutine": 2,
      "ClientPhones": null,
      "ClientEmails": null
    }
  ]
}
```

In this example:

* every `###` marker is assigned to client `686185`
* every `@@@` marker is assigned to client `569520`
* `SignerNumberInRoutine` maps each marker to signer `1` and signer `2`

This is the best option when your routine uses known clients and you already have their IDs.

#### Example 2 - No `ClientId`, signer details sent in the request

Use this when the signers do not have saved client records, or when you want to send to one-time recipients directly from the request.

Set `ClientId` to `null`, then provide the signer details in the same object. In this mode, include `ClientName` and at least one delivery channel such as `ClientEmails` or `ClientPhones`.

```json
{
  "TaskSubject": "Signature routine ASCII no ClientId",
  "TaskGuid": "{{TaskGuid}}",
  "PdfGuid": "{{PdfGuid}}",
  "Language": 1,
  "LanguageMarked": "he",
  "IsSendOnCreation": true,
  "SignatureRoutine": true,
  "SignatureRoutineAsync": true,
  "GroupId": null,
  "SearchWordForSignatureRoutine": [
    {
      "ClientId": null,
      "SearchCharSignature": "$",
      "SignaturePositionFieldType": 0,
      "SignerNumberInRoutine": 1,
      "ClientEmails": "rotemkago@gmail.com",
      "ClientPhones": "0505950786",
      "ClientName": "Clien API 1"
    },
    {
      "ClientId": null,
      "SearchCharSignature": "^",
      "SignaturePositionFieldType": 0,
      "SignerNumberInRoutine": 2,
      "ClientEmails": "rotem0393@gmail.com",
      "ClientPhones": "0505950786",
      "ClientName": "Clien API 2"
    }
  ]
}
```

In this example:

* `$` creates the field for the first signer
* `^` creates the field for the second signer
* the recipient details come directly from `ClientName`, `ClientEmails`, and `ClientPhones`

This is useful for ad hoc routines where you do not want to create or look up client records first.

{% hint style="info" %}
`SignatureRoutineAsync: true` sends the routine in parallel. If signing order matters, set `SignatureRoutineAsync` to `false`. `SignerNumberInRoutine` should still match the intended signer in both modes.
{% endhint %}

{% hint style="warning" %}
Use unique marker values for each signer, and make sure those markers actually exist in the uploaded PDF. Use rare strings that do not appear naturally in the document text.
{% endhint %}


---

# 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/signature-routine-tasks/defining-signature-fields-signature-routine.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.