E-Signature Folders

Folders are the filing system for signing envelopes: nestable, shareable, and many-to-many with the envelopes inside them. Filing links an envelope to a folder rather than moving it, so one contract can sit under several folders at once.

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. Folder and envelope IDs are UUID strings; user IDs are the usual opaque ID strings. See the Poweruser API overview for authentication and conventions.

How filing works

A folder holds links to envelopes, not the envelopes themselves. Three consequences worth designing around:

An envelope can be in many folders. Adding it to a second folder does not remove it from the first. To move it, add to the new folder and remove from the old one.
Deleting a folder never deletes envelopes. The folder, its nested subfolders, their share grants, and all envelope links cascade away; every envelope survives and simply becomes unfiled.
Folders nest via parentId, and share independently of both their parent and their contents. Sharing a folder does not grant access to the envelopes filed in it — envelopes carry their own sharing.

Folder membership is reflected on envelopes: both the envelope object and envelope summaries carry a folderIds array, where [] means unfiled.

The folder object

Returned by create, get, rename, share, and unshare, and as array entries on list.

Name
id
Type
uuid
Description
Unique folder identifier.
Name
name
Type
string
Description
Display name.
Name
parentId
Type
uuid
Description
The parent folder for nesting, or null at top level.
Name
ownerUserId
Type
string
Description
The user who owns the folder. The owner always holds implicit ADMIN.
Name
sharingLevel
Type
string
Description
Baseline visibility: PRIVATE, SPECIFIC_MEMBER, or COMPANY.
Name
myAccessLevel
Type
string
Description
The calling user's effective access on this folder: READ, WRITE, PUBLISH, or ADMIN.
Name
iAmOwner
Type
boolean
Description
Whether the calling user owns the folder.
Name
shares
Type
array<SharePermission>
Description
Explicit per-user grants (userId, userEmail, userName, accessLevel, grantedBy, createdAt). The owner is not included. Populated on single-folder responses; null on list to keep the response light.
Name
envelopeCount
Type
integer
Description
Envelopes linked directly to this folder. Does not include envelopes in nested subfolders.
Name
createdAt
Type
string
Description
ISO 8601 creation timestamp.
Name
updatedAt
Type
string
Description
ISO 8601 timestamp of the last change.

Folder object
{
  "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
  "name": "Northwind",
  "parentId": "f1a0b2c3-4d5e-6f70-8192-a3b4c5d6e7f8",
  "ownerUserId": "uK4pV8sM3d",
  "sharingLevel": "SPECIFIC_MEMBER",
  "myAccessLevel": "ADMIN",
  "iAmOwner": true,
  "shares": [
    {
      "userId": "uQ7nR2tW9e",
      "userEmail": "sam@acme.com",
      "accessLevel": "READ",
      "grantedBy": "uK4pV8sM3d",
      "createdAt": "2026-07-02T09:14:22Z"
    }
  ],
  "envelopeCount": 12,
  "createdAt": "2026-06-18T11:03:41Z",
  "updatedAt": "2026-07-02T09:14:22Z"
}

Create a folder

POST/e-signature/folder/create

Creates a folder in the caller's company. Omit parentId for a top-level folder, or pass one to nest.

Request parameters

Name
name
Type
string
Description
Display name for the folder.
Name
parentId
Type
uuid
Description
Parent folder to nest under. Omit or null for top level.

Response

Name
folder
Type
Folder
Description
The new folder object, owned by the calling user and PRIVATE by default.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/create \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind",
    "parentId": "f1a0b2c3-4d5e-6f70-8192-a3b4c5d6e7f8"
  }'

Response
{
  "folder": {
    "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "name": "Northwind",
    "parentId": "f1a0b2c3-4d5e-6f70-8192-a3b4c5d6e7f8",
    "ownerUserId": "uK4pV8sM3d",
    "sharingLevel": "PRIVATE",
    "myAccessLevel": "ADMIN",
    "iAmOwner": true,
    "shares": [],
    "envelopeCount": 0,
    "createdAt": "2026-06-18T11:03:41Z",
    "updatedAt": "2026-06-18T11:03:41Z"
  },
  "errors": []
}

List folders

POST/e-signature/folder/list

Returns every folder in the company that the caller can see — owned, explicitly granted, or visible through a COMPANY baseline — ordered by name. The whole set comes back unpaginated so a client can build the tree from parentId in one call.

Request parameters

No parameters. Send an empty JSON object.

Response

Name
folders
Type
array<Folder>
Description
Visible folder objects. shares is null on each entry — fetch a single folder with /folder/get for its grant list.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/list \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (truncated)
{
  "folders": [
    {
      "id": "f1a0b2c3-4d5e-6f70-8192-a3b4c5d6e7f8",
      "name": "Clients",
      "parentId": null,
      "sharingLevel": "COMPANY",
      "myAccessLevel": "ADMIN",
      "iAmOwner": true,
      "shares": null,
      "envelopeCount": 0
    },
    {
      "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
      "name": "Northwind",
      "parentId": "f1a0b2c3-4d5e-6f70-8192-a3b4c5d6e7f8",
      "sharingLevel": "PRIVATE",
      "myAccessLevel": "ADMIN",
      "iAmOwner": true,
      "shares": null,
      "envelopeCount": 12
    }
  ],
  "errors": []
}

Get a folder

POST/e-signature/folder/get

Fetches a single folder including its full per-user grant list — the authoritative source for a sharing UI.

Request parameters

Name
folderId
Type
uuid
Description
The folder to fetch.

Response

Name
folder
Type
Folder
Description
The folder object, with shares populated.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/get \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15" }'

Response (truncated)
{
  "folder": {
    "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "name": "Northwind",
    "sharingLevel": "SPECIFIC_MEMBER",
    "myAccessLevel": "ADMIN",
    "shares": [
      {
        "userId": "uQ7nR2tW9e",
        "userEmail": "sam@acme.com",
        "accessLevel": "READ"
      }
    ],
    "envelopeCount": 12
  },
  "errors": []
}

Rename a folder

POST/e-signature/folder/rename

Changes a folder's display name. Requires WRITE access or ownership.

Request parameters

Name
folderId
Type
uuid
Description
The folder to rename.
Name
newName
Type
string
Description
The new display name.

Response

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

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/rename \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "newName": "Northwind Traders"
  }'

Response (truncated)
{
  "folder": {
    "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "name": "Northwind Traders",
    "updatedAt": "2026-07-04T16:22:08Z"
  },
  "errors": []
}

Add envelopes to a folder

POST/e-signature/folder/add-envelopes

Links one or more envelopes to a folder. Filing does not move an envelope — it can belong to several folders at once. The call is idempotent: envelopes already in the folder are skipped and not counted.

Request parameters

Name
folderId
Type
uuid
Description
The destination folder.
Name
envelopeIds
Type
array<uuid>
Description
The envelopes to file.

Response

Name
changedCount
Type
integer
Description
How many links were actually created, excluding idempotent no-ops.
Name
folderId
Type
uuid
Description
The folder that was modified.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/add-envelopes \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "envelopeIds": [
      "e3b1c6a2-9f4d-4c8e-b7a1-2d5f8c9e0a13",
      "e7d2f804-1a3b-4c5d-9e0f-8a1b2c3d4e5f"
    ]
  }'

Response
{
  "changedCount": 2,
  "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
  "errors": []
}

Remove envelopes from a folder

POST/e-signature/folder/remove-envelopes

Unlinks envelopes from a folder. The envelopes themselves are untouched — removing the last link simply leaves an envelope unfiled. Also idempotent.

Request parameters

Name
folderId
Type
uuid
Description
The folder to remove from.
Name
envelopeIds
Type
array<uuid>
Description
The envelopes to unfile.

Response

Name
changedCount
Type
integer
Description
How many links were actually removed, excluding idempotent no-ops.
Name
folderId
Type
uuid
Description
The folder that was modified.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/remove-envelopes \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "envelopeIds": ["e3b1c6a2-9f4d-4c8e-b7a1-2d5f8c9e0a13"]
  }'

Response
{
  "changedCount": 1,
  "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
  "errors": []
}

POST/e-signature/folder/share

Updates the folder'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.

Sharing a folder shares the folder itself. It does not grant access to the envelopes filed inside it; those carry their own sharing.

Request parameters

Name
folderId
Type
uuid
Description
The folder 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
folder
Type
Folder
Description
The updated folder 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/folder/share \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": [
      { "userId": "uQ7nR2tW9e", "accessLevel": "READ" }
    ]
  }'

Response (truncated)
{
  "folder": {
    "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": [
      {
        "userId": "uQ7nR2tW9e",
        "userEmail": "sam@acme.com",
        "accessLevel": "READ"
      }
    ]
  },
  "errors": []
}

Unshare a folder

POST/e-signature/folder/unshare

Revokes a single user's explicit grant on a folder. Does not change the baseline sharingLevel — a COMPANY folder stays visible to everyone after an individual grant is removed.

Request parameters

Name
folderId
Type
uuid
Description
The folder to revoke access on.
Name
userId
Type
string
Description
The user whose grant is revoked.

Response

Name
folder
Type
Folder
Description
The updated folder object with the grant removed.
Name
errors
Type
array<string>
Description
Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/unshare \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "userId": "uQ7nR2tW9e"
  }'

Response (truncated)
{
  "folder": {
    "id": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15",
    "sharingLevel": "SPECIFIC_MEMBER",
    "shares": []
  },
  "errors": []
}

Delete a folder

POST/e-signature/folder/delete

Deletes a folder. Nested subfolders, share grants, and envelope links are removed with it. Envelopes are never deleted — they simply become unfiled. Requires ADMIN access or ownership.

Request parameters

Name
folderId
Type
uuid
Description
The folder to delete.

Response

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

cURL
curl https://api.autessa.com/autessa_poweruser/e-signature/folder/delete \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "f2c7a91e-3b5d-4e8f-9a1c-6d0e2f4b8c15" }'

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

Errors

Status	When
`200`	Success — check `errors` for validation messages (unknown folder, unknown envelope, invalid parent).
`401`	Invalid or missing poweruser key, or the linked user lacks the required access level on the folder.
`403`	Scoped key without the endpoint in its allow-list.
`408`	Server-side error; `errors` contains the message.

How filing works​

The folder object​

Create a folder​

Request parameters​

Response​

List folders​

Request parameters​

Response​

Get a folder​

Request parameters​

Response​

Rename a folder​

Request parameters​

Response​

Add envelopes to a folder​

Request parameters​

Response​

Remove envelopes from a folder​

Request parameters​

Response​

Share a folder​

Request parameters​

Response​

Unshare a folder​

Request parameters​

Response​

Delete a folder​

Request parameters​

Response​

Errors​

Related​

How filing works

The folder object

Create a folder

Request parameters

Response

List folders

Request parameters

Response

Get a folder

Request parameters

Response

Rename a folder

Request parameters

Response

Add envelopes to a folder

Request parameters

Response

Remove envelopes from a folder

Request parameters

Response

Share a folder

Request parameters

Response

Unshare a folder

Request parameters

Response

Delete a folder

Request parameters

Response

Errors

Related