---
updatedAt: 2026-10-19T23:48:42.000Z
agentTools:
  projectIndex: https://docs.signeasy.com/llms.txt
---

# Update template

Change a template's name, message, roles, fields, and merge fields. `is_ordered` and `roles` are required on every call.

Update an uploaded or existing template's name, message, roles, fields, and merge fields.

You can also use this endpoint to pre-configure a template before you embed the template to complete the setup using the [fetch embedded template create URL](https://docs.signeasy.com/reference/fetch-embedded-template-create-url) endpoint.

<Callout icon="fad fa-file-pen" theme="default">
  ### Pre-fill by Sender or Earlier Signers

  Make a `text`, `checkbox`, or `combobox` field pre-fillable by giving it a `label` and a `fillable_by`. For pre-fill by sender, set `fillable_by.sender` to `true`, then pass the value in `merge_fields` using that label when you send from the template. For pre-fill by earlier signers, list the roles in `fillable_by.roles` and set `is_ordered` to `true`. Both are available only on the **API Advanced Plan**. Merge fields for templates (the `merge_fields` array on this endpoint) stay available on all API plans. Reach support or sales for more details.
</Callout>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "signeasy-api-v3",
    "version": "3"
  },
  "servers": [
    {
      "url": "https://api.signeasy.com/v3"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your access token in the `Authorization` header as `Bearer <access_token>`."
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/template/{template_id}": {
      "put": {
        "summary": "Update template",
        "description": "Change a template's name, message, roles, fields, and merge fields. `is_ordered` and `roles` are required on every call.",
        "operationId": "update-template",
        "parameters": [
          {
            "name": "template_id",
            "in": "path",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "is_ordered",
                  "roles"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name of the source document. As a security measure the /, :, *, \\, <, >, | characters are not allowed in the name property in the API request.",
                    "default": "Sample Template Name"
                  },
                  "is_ordered": {
                    "type": "boolean",
                    "description": "When set to `true` the recipients will sign the documents in the specified order. Must be `true` when a field's `fillable_by.roles` lets an earlier role pre-fill it.",
                    "default": true
                  },
                  "roles": {
                    "type": "array",
                    "description": "A collection of role objects to specify the role related metadata for the signer(s).",
                    "items": {
                      "properties": {
                        "role_id": {
                          "type": "integer",
                          "description": "A unique identifier for the role. You can use this to refer to this role in further declarations.",
                          "default": 1
                        },
                        "name": {
                          "type": "string",
                          "description": "A helpful name or title or designation of the signer's role."
                        }
                      },
                      "type": "object"
                    }
                  },
                  "fields_payload": {
                    "type": "array",
                    "description": "Programmatically place fields on the documents based on x-y coordinates or a reference text.",
                    "items": {
                      "properties": {
                        "role_id": {
                          "type": "integer",
                          "description": "The role identifier defined in the `roles` object to whom this field should be assigned to.",
                          "default": 1
                        },
                        "type": {
                          "type": "string",
                          "description": "The type can be one of `signature`, `initials`, `stamp`, `date`, `name`, `text`, `email`, `checkbox`, or `combobox` (dropdown). Only `text`, `checkbox`, and `combobox` fields can be pre-filled.",
                          "default": "signature"
                        },
                        "page_number": {
                          "type": "integer",
                          "description": "The page number to place the field on, as an integer. Example: **4**.",
                          "default": 1
                        },
                        "position": {
                          "type": "object",
                          "description": "Defines where to place the field based on a fixed co-ordinates or a reference text mode.",
                          "required": [
                            "mode",
                            "height",
                            "width"
                          ],
                          "properties": {
                            "mode": {
                              "type": "string",
                              "description": "The value can either be `fixed` or `referenceText`. If you specify the value as `fixed`, then **x** and **y** are mandatory. Else if the value is `referenceText`, **text** is mandatory.",
                              "default": "fixed"
                            },
                            "x": {
                              "type": "integer",
                              "description": "The x coordinate from the bottom left of the page. The **mode** must be `fixed` to use this.",
                              "default": 100,
                              "format": "int32"
                            },
                            "y": {
                              "type": "integer",
                              "description": "The y coordinate from the bottom left. The **mode** must be `fixed` to use this.",
                              "default": 100,
                              "format": "int32"
                            },
                            "height": {
                              "type": "integer",
                              "description": "The height of the field in pixels.",
                              "default": 200,
                              "format": "int32"
                            },
                            "width": {
                              "type": "integer",
                              "description": "The width of the field in pixels.",
                              "default": 250,
                              "format": "int32"
                            },
                            "text": {
                              "type": "string",
                              "description": "The `string` you specify here will be used to parse the document to place the field. The **mode** must be set to `referenceText` to use this.",
                              "default": "Signature"
                            },
                            "xOffset": {
                              "type": "integer",
                              "description": "The value by which original x coordinates have to be shifted. Only available when **mode** is set to `referenceText`.",
                              "default": 25,
                              "format": "int32"
                            },
                            "yOffset": {
                              "type": "integer",
                              "description": "The value by which original y coordinates have to be shifted. Only available when **mode** is set to `referenceText`.",
                              "default": 10,
                              "format": "int32"
                            }
                          }
                        },
                        "required": {
                          "type": "boolean",
                          "description": "If set to `true`, the field will be mandatory. Set `false` to make it optional.",
                          "default": true
                        },
                        "additional_info": {
                          "type": "object",
                          "required": [
                            "format"
                          ],
                          "properties": {
                            "format": {
                              "type": "string",
                              "description": "Date format, if the field is of type `date`."
                            },
                            "options": {
                              "type": "array",
                              "description": "The choices for a `combobox` (dropdown) field. Required for a combobox, with at least one option. Example: **[\"Sole Proprietorship\", \"LLC\", \"Corporation\"]**.",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "description": "Extra settings for some field types. Use `format` for `date` fields and `options` for `combobox` fields."
                        },
                        "label": {
                          "type": "string",
                          "description": "The field's pre-fill key. Required for any field with `fillable_by`. When you send from the template, `merge_fields` matches the field by this label, and error messages name the field by it. Example: **Business Legal Name**."
                        },
                        "fillable_by": {
                          "type": "object",
                          "properties": {
                            "sender": {
                              "type": "boolean",
                              "description": "Set to `true` for pre-fill by sender. When you send from the template, pass the value in `merge_fields` using the field's `label`, or fill it in the embedded sending view.",
                              "default": false
                            },
                            "roles": {
                              "type": "array",
                              "description": "For pre-fill by earlier signers. The `role_id`s, as defined in `roles`, of roles that can fill this field. They must sign before the field's owner role, so set `is_ordered` to `true` and list them earlier in `roles`. Don't include the field's own `role_id`. Available only on the **API Advanced Plan**. Example: **[1]**.",
                              "items": {
                                "type": "integer",
                                "format": "int32"
                              }
                            }
                          },
                          "description": "Turns this field into a pre-fill field and sets who can fill it before the role it's assigned to (`role_id`), the sender, earlier roles, or both. Works only on `text`, `checkbox`, and `combobox` fields, and the field needs a `label`. The recipient in the owner role sees every pre-filled value and can always change it. Pre-fill by sender and pre-fill by earlier signers are available only on the **API Advanced Plan**. Pre-fill by earlier signers also needs `is_ordered` set to `true`."
                        }
                      },
                      "required": [
                        "role_id",
                        "type",
                        "page_number",
                        "required"
                      ],
                      "type": "object"
                    }
                  },
                  "merge_fields": {
                    "type": "array",
                    "description": "Merge fields for templates. Place `text` fields that only the sender fills when sending from the template. They don't belong to any role. Available on the **API Intermediate Plan** and the **API Advanced Plan**, and in any sandbox app. For a field that a role owns and can still edit, use pre-fill by sender instead (`label` and `fillable_by` in `fields_payload`).",
                    "items": {
                      "properties": {
                        "page_number": {
                          "type": "integer",
                          "description": "The page number to place the merge field on, as an integer. Example: **4**.",
                          "default": 1
                        },
                        "position": {
                          "type": "object",
                          "description": "Defines where to place the field based on a fixed co-ordinates or a reference text mode.",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "description": "The value can either be `fixed` or `referenceText`. If you specify the value as `fixed`, then **x** and **y** are mandatory. Else if the value is `referenceText`, **text** is mandatory.",
                              "default": "fixed"
                            },
                            "x": {
                              "type": "integer",
                              "description": "The x coordinate from the bottom left of the page. The **mode** must be `fixed` to use this.",
                              "format": "int32",
                              "default": 100
                            },
                            "y": {
                              "type": "integer",
                              "description": "The y coordinate from the bottom left. The **mode** must be `fixed` to use this.",
                              "format": "int32",
                              "default": 100
                            },
                            "height": {
                              "type": "integer",
                              "description": "The height of the field in pixels.",
                              "format": "int32",
                              "default": 200
                            },
                            "width": {
                              "type": "integer",
                              "description": "The width of the field in pixels.",
                              "default": 250,
                              "format": "int32"
                            },
                            "text": {
                              "type": "string",
                              "description": "The `string` you specify here will be used to parse the document to place the field. The **mode** must be set to `referenceText` to use this.",
                              "default": "Signature"
                            },
                            "xOffset": {
                              "type": "integer",
                              "description": "The value by which original x coordinates have to be shifted. Only available when **mode** is set to `referenceText`.",
                              "format": "int32",
                              "default": 25
                            },
                            "yOffset": {
                              "type": "integer",
                              "description": "The value by which original y coordinates have to be shifted. Only available when **mode** is set to `referenceText`.",
                              "format": "int32",
                              "default": 10
                            }
                          },
                          "required": [
                            "mode",
                            "height",
                            "width"
                          ]
                        },
                        "label": {
                          "type": "string",
                          "description": "A label for the merge field. Use this label to assign value to this merge field when pre-filling the document before sending a signature request.",
                          "default": "Merge label"
                        },
                        "required": {
                          "type": "boolean",
                          "description": "If set to `true`, the field will be mandatory. Set `false` to make it optional.",
                          "default": true
                        }
                      },
                      "required": [
                        "page_number",
                        "label",
                        "required"
                      ],
                      "type": "object"
                    }
                  },
                  "message": {
                    "type": "string",
                    "description": "The message you provide here will be displayed in the signing interface to the signers along with the document.",
                    "default": "This is a test message"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"group_info\": null,\n    \"id\": 24255,\n    \"owner_user_id\": 3675808,\n    \"name\": \"Sample Template Name\",\n    \"metadata\": {\n        \"roles\": [\n            {\n                \"id\": 1,\n                \"name\": \"One\",\n                \"color\": \"rgba(78, 116, 243, 0.2)\"\n            }\n        ],\n        \"fields\": [\n            {\n                \"id\": 1,\n                \"type\": \"signature\",\n                \"sub_type\": null,\n                \"additional_info\": null,\n                \"required\": true,\n                \"editable\": null,\n                \"role_id\": 1,\n                \"group_id\": null,\n                \"page_number\": 1,\n                \"position\": {\n                    \"x\": 113.369565,\n                    \"y\": 690.322464,\n                    \"width\": 70.0,\n                    \"height\": 20.0,\n                    \"mode\": null\n                }\n            }\n        ],\n        \"merge_fields\": [\n            {\n                \"id\": 2,\n                \"type\": \"text\",\n                \"sub_type\": null,\n                \"additional_info\": {\n                    \"label\": \"Merge label\",\n                    \"merge_field\": true\n                },\n                \"required\": true,\n                \"editable\": null,\n                \"group_id\": null,\n                \"page_number\": 1,\n                \"position\": {\n                    \"x\": 333.09058,\n                    \"y\": 626.619565,\n                    \"width\": 176.0,\n                    \"height\": 20.0,\n                    \"mode\": \"fixed\"\n                }\n            }\n        ]\n    },\n    \"message\": \"This is a test message.\",\n    \"is_ordered\": false,\n    \"created_time\": 1700460896.0,\n    \"modified_time\": 1700468998.0,\n    \"is_shared\": false,\n    \"is_owned\": true,\n    \"attributes\": null,\n    \"file_status\": \"READY_TO_USE\",\n    \"is_shared_with_everyone\": false,\n    \"file_content_type\": \"application/pdf\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "group_info": {},
                    "id": {
                      "type": "integer",
                      "example": 24255,
                      "default": 0
                    },
                    "owner_user_id": {
                      "type": "integer",
                      "example": 3675808,
                      "default": 0
                    },
                    "name": {
                      "type": "string",
                      "example": "Sample Template Name"
                    },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "roles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "name": {
                                "type": "string",
                                "example": "One"
                              },
                              "color": {
                                "type": "string",
                                "example": "rgba(78, 116, 243, 0.2)"
                              }
                            }
                          }
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "type": {
                                "type": "string",
                                "example": "signature"
                              },
                              "sub_type": {},
                              "additional_info": {},
                              "required": {
                                "type": "boolean",
                                "example": true,
                                "default": true
                              },
                              "editable": {},
                              "role_id": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "group_id": {},
                              "page_number": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "position": {
                                "type": "object",
                                "properties": {
                                  "x": {
                                    "type": "number",
                                    "example": 113.369565,
                                    "default": 0
                                  },
                                  "y": {
                                    "type": "number",
                                    "example": 690.322464,
                                    "default": 0
                                  },
                                  "width": {
                                    "type": "integer",
                                    "example": 70,
                                    "default": 0
                                  },
                                  "height": {
                                    "type": "integer",
                                    "example": 20,
                                    "default": 0
                                  },
                                  "mode": {}
                                }
                              }
                            }
                          }
                        },
                        "merge_fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "example": 2,
                                "default": 0
                              },
                              "type": {
                                "type": "string",
                                "example": "text"
                              },
                              "sub_type": {},
                              "additional_info": {
                                "type": "object",
                                "properties": {
                                  "label": {
                                    "type": "string",
                                    "example": "Merge label"
                                  },
                                  "merge_field": {
                                    "type": "boolean",
                                    "example": true,
                                    "default": true
                                  }
                                }
                              },
                              "required": {
                                "type": "boolean",
                                "example": true,
                                "default": true
                              },
                              "editable": {},
                              "group_id": {},
                              "page_number": {
                                "type": "integer",
                                "example": 1,
                                "default": 0
                              },
                              "position": {
                                "type": "object",
                                "properties": {
                                  "x": {
                                    "type": "number",
                                    "example": 333.09058,
                                    "default": 0
                                  },
                                  "y": {
                                    "type": "number",
                                    "example": 626.619565,
                                    "default": 0
                                  },
                                  "width": {
                                    "type": "integer",
                                    "example": 176,
                                    "default": 0
                                  },
                                  "height": {
                                    "type": "integer",
                                    "example": 20,
                                    "default": 0
                                  },
                                  "mode": {
                                    "type": "string",
                                    "example": "fixed"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "example": "This is a test message."
                    },
                    "is_ordered": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "created_time": {
                      "type": "integer",
                      "example": 1700460896,
                      "default": 0
                    },
                    "modified_time": {
                      "type": "integer",
                      "example": 1700468998,
                      "default": 0
                    },
                    "is_shared": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "is_owned": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "attributes": {},
                    "file_status": {
                      "type": "string",
                      "example": "READY_TO_USE"
                    },
                    "is_shared_with_everyone": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "file_content_type": {
                      "type": "string",
                      "example": "application/pdf"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The body fails validation",
            "content": {
              "application/json": {
                "examples": {
                  "is_ordered missing": {
                    "value": {
                      "error_code": "validation failure",
                      "msg": "Invalid template update body: Required field '<obj>.is_ordered' is missing"
                    }
                  },
                  "role_id not an integer": {
                    "value": {
                      "error_code": "validation failure",
                      "msg": "Invalid template update body: Value '1' for field '<obj>.roles[0].role_id' is not of type integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid access token, or the template doesn't exist or isn't yours",
            "content": {
              "application/json": {
                "examples": {
                  "Invalid token": {
                    "value": {
                      "error": "unauthorized",
                      "message": "The server could not verify that you are authorized to accessthe URL requested. You either supplied the wrong authorization token,or you used an authorization token which doesn't have required scopes."
                    }
                  },
                  "Template not found": {
                    "value": {
                      "message": "Unauthorized",
                      "error_code": "unauthorized_resource"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```