Create Sign Operation

Use of this endpoint allows the creation of a new operation. A wide range of optional parameters is available in order to support highly specialized use cases. However, not all parameters are typically required, and their quantity may be overwhelming at first. It is recommended to review the examples provided in the /examples folder – in our postman collection –, which cover common use cases that may align with the intended implementation.

To initiate an operation, it is necessary to provide a PDF file—either encoded in Base64 or by specifying the ID of a previously uploaded template. Additionally, optional configuration options and a list of signatories must be included.

Files array

The files array is the main object used to define the operation(s) to be created. In most scenarios, this array will contain a single entry, as only one PDF is to be sent to one or more signers. If multiple file objects are provided, multiple operations will be created. These operations can be chained (see the following table), requiring signers to complete the first operation before proceeding to the next. This structure is referred to as a “chained operation”

To send multiple PDFs and allow signers to review and sign all documents within a single operation using just one signature, refer to the Create Envelope endpoing . This alternative allows users to sign all documents collectively in a single step.

File object

Inside the files array there must be at least one object with this parameters included.

Configure object

This object is optional, also all parameters inside it are optional so you can omit it**.** It allows you to configure global options of the operation, but don't forget to take a look to the receivers parameter (next table) for some specific configurations applied per signer that are not possible to set in this object

** Format

{
    "document_id": (string) "the id of the document",
    "status": (int 0,
    2,
    4,
    6) the status,
    "expired": (boolean) is document expired?,
    "post_callback_url_token": optional sec. token (see next param)
}

Example

{
    "document_id": "6578acas5678cd56",
    "status": 2,
    "expired": false
}

Receivers array

The receivers object represents the signers of the operation, making it possible to declare them and make a specific configuration for each one. At least one receiver is required.

Form Elements

Form elements are interactive fields that signers can fill out during the signing process. These elements are later stamped onto the document once it has been signed. A common use case is the inclusion of a signature box, which allows the signer’s signature to be visually placed in the final PDF.

Defining formElements manually via the API can be complex due to the precise positioning and structure required. For this reason, the recommended approach is to preconfigure a template or layout using the Tecalis Signature Admin Panel, including all desired form fields. These can then be reused when defining the formElements array for the recipient(s).

Once a template or layout is created, the get template/layout info method can be used to retrieve its associated formElements. These elements may be reused with minimal adjustments — typically, only the "page" attribute must be updated to indicate where each element should appear, since the "position" values are already correctly defined in the template.

Note: If the same form element needs to be reused multiple times within the same operation, it is strongly recommended to regenerate a unique "uuid" for each instance to avoid unexpected behavior during the signing process.

There are two ways to define formElements in an operation:

By reference – Provide a template_id or layout_id to import the form elements directly from an existing template. This is ideal when no modifications are required.

{
    "formElements": [
        {
            "template_id": "631f060a0c85c750720462c2"
        }
    ]
}

Manually – Include the full JSON structure of the formElements when custom changes are needed (e.g. modifying the "page", "uuid", or other attributes).

{
    "formElements": [
        {
            "uuid": "c674a18e-e833-457b-8cfd-e448f1a1add2",
            "type": "signature",
            "name": "signature",
            "page": 1,
            "x": 104,
            "y": -185,
            "w": 203,
            "h": 149,
            "oldW": 200,
            "oldH": 100,
            "label": "",
            "dragCache": {
                "x": 104,
                "y": 185
            },
            "value": null,
            "required": false,
            "disabled": false,
            "visible": true,
            "percentages": {
                "x": 0.08573784006595218,
                "y": -0.1077744466615623,
                "w": 0.16735366859027206,
                "h": 0.08680212190579882
            },
            "pdfDisplayerDocumentWidth": 1213,
            "pdfDisplayerDocumentHeight": 1716.5478991596638
        },
        {
            "uuid": "dde72edc-6f4b-430d-a8fa-fee7515a6108",
            "type": "textbox",
            "name": "textbox",
            "page": 1,
            "x": 104,
            "y": -341,
            "w": 202,
            "h": 39,
            "oldW": 180,
            "oldH": 38,
            "label": "",
            "dragCache": {
                "x": 104,
                "y": 341
            },
            "value": null,
            "required": false,
            "disabled": false,
            "visible": true,
            "percentages": {
                "x": 0.08573784006595218,
                "y": -0.19865452060320402,
                "w": 0.1665292662819456,
                "h": 0.022720018485410432
            },
            "pdfDisplayerDocumentWidth": 1213,
            "pdfDisplayerDocumentHeight": 1716.5478991596638
        }
    ]
}

Both methods can be combined in a single request. Additionally, it is possible to provide multiple template_id values to compose a more complex form structure.

{
    "formElements": [
        {
            "template_id": "631f060a0c85c750720462c2"
        },
        //{
        //    "layout_id": "631f05d0e6830e72c16f23e2"
        //},
        {
            "uuid": "dde72edc-6f4b-430d-a8fa-fee7515a6108",
            "type": "textbox",
            "name": "textbox",
            "page": 1,
            "x": 104,
            "y": -341,
            "w": 202,
            "h": 39,
            "oldW": 180,
            "oldH": 38,
            "label": "",
            "dragCache": {
                "x": 104,
                "y": 341
            },
            "value": null,
            "required": false,
            "disabled": false,
            "visible": true,
            "percentages": {
                "x": 0.08573784006595218,
                "y": -0.19865452060320402,
                "w": 0.1665292662819456,
                "h": 0.022720018485410432
            },
            "pdfDisplayerDocumentWidth": 1213,
            "pdfDisplayerDocumentHeight": 1716.5478991596638
        }
    ]
}

Modifying Form Elements

It is possible to modify the properties of the form fields placed within a document. The most common modifications typically involve changing the page where the field is displayed or updating its assigned value. These modifications can be performed either dynamically or statically, with each approach offering specific advantages and disadvantages.

The only difference between both approaches lies in how the form elements are obtained — the final structure and submission process are the same.

Retrieving Form Elements

Dynamically

Form elements can be retrieved in real time by calling the endpoint pdf/template/:id/info or pdf/layout/:id/info, depending on whether the source is a template or a layout.

Pros:

• The most up-to-date version of the form elements is always retrieved.
• No need to maintain or version external copies of the configuration.

Cons:

• Requires an additional API call, which may increase response time.
• If multiple users have access to the Tecalis Signature Admin Panel, fields may be modified unexpectedly, leading to inconsistencies if not properly controlled.

Statically

Form elements are retrieved once using the same endpoints (pdf/template/:id/info or pdf/layout/:id/info) and stored locally in a static JSON file for later use.

Pros:

• Prevents unexpected changes due to admin panel updates by other users.
• Ideal for scenarios where field consistency is critical.

Cons:

• Stored form elements may become outdated if changes are made in the admin panel.
• Requires manual management to keep the static data in sync with template updates.

Editing Form Elements

To modify a field, its uuid must be known. Alternatively, the name attribute can be used, but only if it is guaranteed to be unique across the form elements to avoid unexpected behavior.

Once the target field is identified (using uuid or name), its properties can be updated — commonly the page or value attributes.

Submitting Modified Fields

After the required modifications are applied, the resulting JSON object should be submitted via the formElements parameter within the relevant API request, template or layout over the PDF of another template

Template/Layout over template

It is possible to apply the form elements defined in one template or layout (Template A) to the PDF file of a different template (Template B).

This approach provides greater flexibility, allowing the combination of predefined field configurations with different document contents. When doing so, it is important to ensure that the positioning and pagination of the fields are compatible with the target PDF.

{
    "files": [
        {
            "receivers": [
                {
                    "email": "[email protected]",
                    "formElements": [
                        {
                            "template_id": "631f060a0c85c750720462c2"
                        }
                    ]
                }
            ],
            "configure": {},
            "name": "Template test",
            "template_id": "631f05d0e6830e72c16f23e2"
        }
    ]
}

KYC in receivers

Example

{
    "kyc": {
        "mode": "auto",
        "with_selfie": true,
        "additional_documents": [
            {
                "name": "Insurance first two pages",
                "subtext": "Send first and second page of your insurance contract",
                "required": true,
                "copies": 2,
                "extensions": "all",
                "capture_mode": "photo_upload",
                "instructions": "Take  photos or upload  scanned images of the first and second page of your insurance contract"
            }
        ]
    }
}

View in the API