E-Signature Templates

Turn a recurring document into a reusable template: fix the PDF and field layout once, define named roles instead of concrete signers, then stamp out ready-to-send envelopes by binding each role to real people.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/e-signature. Every request is a POST with a JSON body. Template, role, and field IDs are UUID strings; user IDs are the usual opaque ID strings. See the Poweruser API overview for authentication and conventions.

Template → envelope instantiation

A template is the same building blocks as an envelope — a PDF plus a field layout — with one difference: instead of recipients, fields bind to roles (for example "Client", "Contractor"). Roles carry the same signer-slot semantics as recipients (orderIndex, signingGroup).

The lifecycle:

Upload the PDF via /generate-file-upload-link and register it with /template/create.
Define roles with /template/roles and place fields with /template/fields, referencing roleId instead of recipientId.
Call /template/create-envelope with a roleAssignments list binding each role to one or more real recipients. This clones the PDF and field layout into a normal DRAFT envelope — tweak it if needed, then send it via /envelope/send.

Instantiation copies; it does not link. Later edits to the template never affect envelopes already created from it.

The template object

Returned by create, get, set-roles, set-fields, share, and unshare.

Name
id
Type
uuid
Description
Unique template identifier.
Name
companyId
Type
string
Description
Owning company.
Name
ownerUserId
Type
string
Description
The user who owns the template.
Name
title
Type
string
Description
Display title. Envelopes created from the template inherit it unless overridden.
Name
description
Type
string
Description
What the template is for.
Name
signingOrder
Type
string
Description
Default signing order inherited by created envelopes: PARALLEL or SEQUENTIAL.
Name
completionPolicy
Type
string
Description
Default completion policy inherited by created envelopes: ALL or ANY_ONE.
Name
sharingLevel
Type
string
Description
PRIVATE, SPECIFIC_MEMBER, or COMPANY.
Name
sha256Original
Type
string
Description
SHA-256 of the template PDF.
Name
viewPdfUrl
Type
string
Description
Time-boxed presigned URL for the template PDF.
Name
roles
Type
array<TemplateRole>
Description
Roles: id (uuid), roleName, orderIndex, signingGroup (roles sharing a slot form a client group once instantiated), colorIndex (used by the Builder's field editor).
Name
fields
Type
array<TemplateField>
Description
Fields, mirroring envelope fields but bound to a roleId when fillSource is SIGNER: id, fillSource, roleId, fieldType, placement (pageIndex, xPct, yPct, widthPct, heightPct, rotation), required, value, valueImageUrl, and font styling (fontFamily, fontSize, fontColor).
Name
shares
Type
array<SharePermission>
Description
Per-user grants (userId, userEmail, userName, accessLevel, grantedBy, grantedByName, createdAt). The owner is not listed — they have implicit ADMIN.
Name
myAccessLevel
Type
string
Description
The calling user's effective access level: READ, WRITE, PUBLISH, or ADMIN.
Name
createdAt
Type
string
Description
ISO-8601 creation timestamp.
Name
updatedAt
Type
string
Description
ISO-8601 timestamp of the last update.
Name
iAmOwner
Type
boolean
Description
Whether the calling user owns the template.

Template object (truncated)
{
  "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
  "companyId": "cP2mK7dX4v",
  "ownerUserId": "uB7nT2wQ9k",
  "title": "Standard NDA",
  "description": "Mutual NDA for vendor engagements.",
  "signingOrder": "PARALLEL",
  "completionPolicy": "ALL",
  "sharingLevel": "COMPANY",
  "viewPdfUrl": "https://s3.amazonaws.com/autessa-esign/...",
  "roles": [
    {
      "id": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
      "roleName": "Counterparty",
      "orderIndex": 1,
      "signingGroup": 1,
      "colorIndex": 0
    }
  ],
  "fields": [
    {
      "id": "f9e8d7c6-b5a4-4321-8f0e-1d2c3b4a5968",
      "fillSource": "SIGNER",
      "roleId": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
      "fieldType": "SIGNATURE",
      "pageIndex": 3,
      "xPct": 12.5, "yPct": 80.0,
      "widthPct": 30.0, "heightPct": 5.0,
      "required": true
    }
  ],
  "shares": [],
  "myAccessLevel": "ADMIN",
  "iAmOwner": true
}

Create a template

POST/e-signature/template/create

Registers a template around a PDF already uploaded via /generate-file-upload-link.

Request parameters

Name
title
Type
string
Description
Template title.
Name
description
Type
string
Description
What the template is for.
Name
s3Uri
Type
string
Description
The S3 URI (or key) returned by the file-upload-link flow.
Name
signingOrder
Type
string
Description
Default signing order for created envelopes; null means PARALLEL.
Name
completionPolicy
Type
string
Description
Default completion policy for created envelopes; null means ALL.

Response

Name
template
Type
Template
Description
The new template object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/e-signature/template/create \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Standard NDA",
    "description": "Mutual NDA for vendor engagements.",
    "s3Uri": "s3://autessa-files/company-cP2mK7dX4v/file-4c8b.pdf",
    "signingOrder": "PARALLEL",
    "completionPolicy": "ALL"
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/e-signature/template/create',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Standard NDA',
      description: 'Mutual NDA for vendor engagements.',
      s3Uri: 's3://autessa-files/company-cP2mK7dX4v/file-4c8b.pdf'
    })
  }
);

const { template } = await response.json();

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/e-signature/template/create',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'title': 'Standard NDA',
        'description': 'Mutual NDA for vendor engagements.',
        's3Uri': 's3://autessa-files/company-cP2mK7dX4v/file-4c8b.pdf'
    }
)

template = response.json()['template']

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "title": "Standard NDA",
    "signingOrder": "PARALLEL",
    "completionPolicy": "ALL",
    "roles": [],
    "fields": [],
    "iAmOwner": true
  },
  "errors": []
}

Get a template

POST/e-signature/template/get

Retrieves a template's full detail: roles, field layout, sharing, and a presigned URL for the PDF.

Request parameters

Name
templateId
Type
uuid
Description
The template to fetch.

Response

Name
template
Type
Template
Description
The template object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/get \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f" }'

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "title": "Standard NDA",
    "roles": [
      { "id": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c", "roleName": "Counterparty" }
    ],
    "myAccessLevel": "ADMIN"
  },
  "errors": []
}

List templates

POST/e-signature/template/list

Lists templates visible to the linked user, with search and pagination.

Request parameters

Name
search
Type
string
Description
Title search string.
Name
page
Type
integer
Description
Page index.
Name
pageSize
Type
integer
Description
Entries per page.

Response

Name
templates
Type
array<TemplateSummary>
Description
Summaries: id, title, description, roleCount, fieldCount, sharingLevel, myAccessLevel, createdAt, updatedAt, iAmOwner, ownerUserId.
Name
total
Type
integer
Description
Total templates across all pages.
Name
page
Type
integer
Description
The page returned.
Name
pageSize
Type
integer
Description
Entries per page.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/list \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "search": "NDA", "page": 0, "pageSize": 20 }'

Response
{
  "templates": [
    {
      "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
      "title": "Standard NDA",
      "description": "Mutual NDA for vendor engagements.",
      "roleCount": 1,
      "fieldCount": 4,
      "sharingLevel": "COMPANY",
      "myAccessLevel": "ADMIN",
      "iAmOwner": true,
      "createdAt": "2026-05-02T11:00:00",
      "updatedAt": "2026-06-20T09:45:12"
    }
  ],
  "total": 3,
  "page": 0,
  "pageSize": 20,
  "errors": []
}

Set roles

POST/e-signature/template/roles

Replaces the template's role list. Include id on an entry to update an existing role; omit it to create a new one. Fields reference roles, so removing a role a field points at invalidates that field binding.

Request parameters

Name
templateId
Type
uuid
Description
The template to update.
Name
roles
Type
array<TemplateRoleInput>
Description
The full role list.
Name
roles[].id
Type
uuid
Description
Present when updating an existing role; omit when adding.
Name
roles[].roleName
Type
string
Description
Role name, for example "Client" or "Contractor".
Name
roles[].orderIndex
Type
integer
Description
1-based position for SEQUENTIAL signing.
Name
roles[].signingGroup
Type
integer
Description
Signer slot (1-based); roles sharing a slot form a client group once instantiated. Null means own slot.
Name
roles[].colorIndex
Type
integer
Description
Color used to render the role's fields in the Builder editor.

Response

Name
template
Type
Template
Description
The updated template object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/roles \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "roles": [
      { "roleName": "Counterparty", "orderIndex": 1, "signingGroup": 1 },
      { "roleName": "Acme Signatory", "orderIndex": 2, "signingGroup": 2 }
    ]
  }'

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "roles": [
      { "id": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c", "roleName": "Counterparty" },
      { "id": "r2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d", "roleName": "Acme Signatory" }
    ]
  },
  "errors": []
}

Set fields

POST/e-signature/template/fields

Fully replaces the template's field set. Identical to envelope field placement, except SIGNER fields reference a roleId instead of a recipientId.

Request parameters

Name
templateId
Type
uuid
Description
The template to update.
Name
fields
Type
array<TemplateFieldInput>
Description
The complete field set.
Name
fields[].id
Type
uuid
Description
Optional on create, required when editing an existing field.
Name
fields[].fillSource
Type
string
Description
SIGNER or PREFILL.
Name
fields[].roleId
Type
uuid
Description
Required when fillSource is SIGNER — the role that fills the field.
Name
fields[].fieldType
Type
string
Description
SIGNER: SIGNATURE, INITIALS, NAME, EMAIL, DATE_SIGNED, TEXT_INPUT, CHECKBOX, DROPDOWN. PREFILL: TEXT_STATIC, DATE_STATIC, IMAGE_STATIC.
Name
fields[].pageIndex
Type
integer
Description
Zero-based PDF page.
Name
fields[].xPct
Type
number
Description
Left edge as a percentage of page width.
Name
fields[].yPct
Type
number
Description
Top edge as a percentage of page height.
Name
fields[].widthPct
Type
number
Description
Width as a percentage of page width.
Name
fields[].heightPct
Type
number
Description
Height as a percentage of page height.
Name
fields[].rotation
Type
integer
Description
Rotation in degrees.
Name
fields[].required
Type
boolean
Description
Whether the signer must fill it.
Name
fields[].value
Type
string
Description
Static text (PREFILL) or baseline display value.
Name
fields[].valueImageS3Key
Type
string
Description
For PREFILL IMAGE_STATIC — S3 key uploaded via the file-upload-link flow.
Name
fields[].fontFamily
Type
string
Description
Render font.
Name
fields[].fontSize
Type
integer
Description
Render font size.
Name
fields[].fontColor
Type
string
Description
Render font color.

Response

Name
template
Type
Template
Description
The updated template object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/fields \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "fields": [
      {
        "fillSource": "SIGNER",
        "roleId": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
        "fieldType": "SIGNATURE",
        "pageIndex": 3,
        "xPct": 12.5, "yPct": 80.0,
        "widthPct": 30.0, "heightPct": 5.0,
        "required": true
      },
      {
        "fillSource": "SIGNER",
        "roleId": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
        "fieldType": "DATE_SIGNED",
        "pageIndex": 3,
        "xPct": 55.0, "yPct": 80.0,
        "widthPct": 20.0, "heightPct": 3.0,
        "required": true
      }
    ]
  }'

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "fields": [
      { "id": "f9e8d7c6-b5a4-4321-8f0e-1d2c3b4a5968", "fieldType": "SIGNATURE" },
      { "id": "f0f9e8d7-c6b5-4432-9a1f-2e3d4c5b6a79", "fieldType": "DATE_SIGNED" }
    ]
  },
  "errors": []
}

Create an envelope from a template

POST/e-signature/template/create-envelope

Instantiates a DRAFT envelope from the template: clones the PDF and field layout, and binds each role to real recipients. The result is a normal envelope — adjust it if needed, then send it via /envelope/send.

Each role assignment takes one primary recipient first, then optional a client group sharing the role's signer slot — any one of them signing satisfies it.

Request parameters

Name
templateId
Type
uuid
Description
The template to instantiate.
Name
title
Type
string
Description
Overrides the template title for the created envelope.
Name
roleAssignments
Type
array<RoleAssignment>
Description
One entry per template role.
Name
roleAssignments[].roleId
Type
uuid
Description
The template role being bound.
Name
roleAssignments[].recipients
Type
array<RecipientInput>
Description
Primary recipient first, then the rest of the client group. At least one required. Each entry: email, name, and optionally recipientKind (SIGNER or VIEWER).

Response

Name
envelope
Type
Envelope
Description
The new DRAFT envelope — see the envelope object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred (for example an unassigned role).

cURL
JavaScript
Python

curl https://api.autessa.com/autessa_poweruser/e-signature/template/create-envelope \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "title": "NDA — Northwind Traders",
    "roleAssignments": [
      {
        "roleId": "r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
        "recipients": [
          { "email": "dana@northwind.com", "name": "Dana Fuentes" }
        ]
      }
    ]
  }'

const response = await fetch(
  'https://api.autessa.com/autessa_poweruser/e-signature/template/create-envelope',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.POWERUSER_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      templateId: 't8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f',
      title: 'NDA — Northwind Traders',
      roleAssignments: [
        {
          roleId: 'r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c',
          recipients: [
            { email: 'dana@northwind.com', name: 'Dana Fuentes' },
            // Client group — shares the role's signer slot
            { email: 'cfo@northwind.com', name: 'Ed Silva' }
          ]
        }
      ]
    })
  }
);

const { envelope } = await response.json();

import os
import requests

response = requests.post(
    'https://api.autessa.com/autessa_poweruser/e-signature/template/create-envelope',
    headers={'Authorization': os.environ['POWERUSER_KEY']},
    json={
        'templateId': 't8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f',
        'title': 'NDA — Northwind Traders',
        'roleAssignments': [
            {
                'roleId': 'r1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c',
                'recipients': [
                    {'email': 'dana@northwind.com', 'name': 'Dana Fuentes'}
                ]
            }
        ]
    }
)

envelope = response.json()['envelope']

Response (truncated)
{
  "envelope": {
    "id": "f4c2d7b3-0a5e-4d9f-c8b2-3e6a9d0f1b24",
    "title": "NDA — Northwind Traders",
    "status": "DRAFT",
    "signingOrder": "PARALLEL",
    "completionPolicy": "ALL",
    "recipients": [
      {
        "email": "dana@northwind.com",
        "name": "Dana Fuentes",
        "signingGroup": 1,
        "status": "PENDING"
      }
    ]
  },
  "errors": []
}

POST/e-signature/template/share

Updates the template's sharing configuration — replaces the per-user grant list and optionally changes the baseline sharing level. The owner has implicit ADMIN and must not appear in shares.

Request parameters

Name
templateId
Type
uuid
Description
The template to share.
Name
sharingLevel
Type
string
Description
PRIVATE, SPECIFIC_MEMBER, or COMPANY.
Name
shares
Type
array<ShareInput>
Description
Replacement per-user grants. Each entry: userId (string) and accessLevel (READ, WRITE, PUBLISH, or ADMIN).

Response

Name
template
Type
Template
Description
The updated template object with the new shares.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/share \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": [
      { "userId": "uK4pV8sM3d", "accessLevel": "WRITE" }
    ]
  }'

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": [
      {
        "userId": "uK4pV8sM3d",
        "userEmail": "sam@acme.com",
        "accessLevel": "WRITE"
      }
    ]
  },
  "errors": []
}

Unshare a template

POST/e-signature/template/unshare

Revokes one user's access grant.

Request parameters

Name
templateId
Type
uuid
Description
The template.
Name
userId
Type
string
Description
The user whose grant to remove.

Response

Name
template
Type
Template
Description
The updated template object.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/unshare \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "userId": "uK4pV8sM3d"
  }'

Response (truncated)
{
  "template": {
    "id": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": []
  },
  "errors": []
}

Delete a template

POST/e-signature/template/delete

Permanently deletes a template. Envelopes already created from it are unaffected — instantiation copies rather than links.

Request parameters

Name
templateId
Type
uuid
Description
The template to delete.

Response

Name
deleted
Type
boolean
Description
Whether the template was deleted.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/template/delete \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "t8d4e9f1-2a6b-4c3d-8e7f-5a9b0c1d2e3f" }'

Response
{
  "deleted": true,
  "errors": []
}

Errors

Status	When
`200`	Success — check `errors` for validation messages (unknown template, missing role assignment, field bound to a removed role).
`401`	Invalid or missing poweruser key, or the linked user lacks access to the template.
`403`	Scoped key without the endpoint in its allow-list.
`408`	Server-side error; `errors` contains the message.

Template → envelope instantiation​

The template object​

Create a template​

Request parameters​

Response​

Get a template​

Request parameters​

Response​

List templates​

Request parameters​

Response​

Set roles​

Request parameters​

Response​

Set fields​

Request parameters​

Response​

Create an envelope from a template​

Request parameters​

Response​

Share a template​

Request parameters​

Response​

Unshare a template​

Request parameters​

Response​

Delete a template​

Request parameters​

Response​

Errors​

Related​

Template → envelope instantiation

The template object

Create a template

Request parameters

Response

Get a template

Request parameters

Response

List templates

Request parameters

Response

Set roles

Request parameters

Response

Set fields

Request parameters

Response

Create an envelope from a template

Request parameters

Response

Share a template

Request parameters

Response

Unshare a template

Request parameters

Response

Delete a template

Request parameters

Response

Errors

Related