Guides

Folders and search

Folders organize envelopes. They never change an envelope's recipients, its validity, or the links people were emailed. Moving an envelope, or deleting the folder it sits in, touches nothing a signer can see.

The folder tree

• Folders belong to a workspace's team. Each has a name (up to 120 characters) and an optional parent_id; a folder with no parent is at the root.
• Names are unique among siblings: two folders at the same level cannot share a name.
• The tree is at most 5 levels deep. depth is 1 for a root folder.
• Folder ids are plain UUIDs scoped to the workspace. Another workspace's id counts as nonexistent.
• Deleting a folder moves its subfolders and envelopes up to its parent; deleting a root folder leaves them unfoldered. Nothing is deleted but the folder itself.
• Every folder has a kind: documents (the default) or templates. The two are separate trees with the same rules; a parent must be of the same kind. Leave kind out and you get envelope folders, as before.

curl -s https://app-staging.signenvoy.com/v1/folders -H "Authorization: Bearer $SENV_API_KEY"

[
    {"id": "8f1a...", "name": "Contracts", "parent_id": null, "depth": 1},
    {"id": "c3d9...", "name": "2026", "parent_id": "8f1a...", "depth": 2}
]

The tree comes back flat; rebuild it from parent_id and depth.

Create one:

curl -s -X POST https://app-staging.signenvoy.com/v1/folders \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "2026", "parent_id": "8f1a..."}'

Rename it, or move it under another parent (move_to_root: true moves it to the top):

curl -s -X PATCH https://app-staging.signenvoy.com/v1/folders/c3d9... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "FY2026"}'

Delete it (204); its contents move up one level:

curl -s -X DELETE https://app-staging.signenvoy.com/v1/folders/c3d9... -H "Authorization: Bearer $SENV_API_KEY"

Template folders

Templates are organized the same way, on their own tree. List it with ?kind=templates, create into it with "kind": "templates", and reference a template folder from POST /v1/templates or PATCH /v1/templates/{id} as folder_id. A patch that carries only folder_id (or "clear_folder": true) is a move, not a new version. GET /v1/templates?folder= narrows to one folder. A envelope folder passed where a template folder belongs, or the reverse, is refused with folder-invalid and a sentence naming the mismatch.

curl -s -X POST https://app-staging.signenvoy.com/v1/folders \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Sales", "kind": "templates"}'

curl -s -X PATCH https://app-staging.signenvoy.com/v1/templates/tpl_... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"folder_id": "5b2e..."}'

Put an envelope in a folder

curl -s -X PATCH https://app-staging.signenvoy.com/v1/documents/doc_... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"folder_id": "c3d9..."}'

Take it out again:

curl -s -X PATCH https://app-staging.signenvoy.com/v1/documents/doc_... \
  -H "Authorization: Bearer $SENV_API_KEY" -H "Content-Type: application/json" \
  -d '{"clear_folder": true}'

A null in a patch means "leave unchanged", which is why removing an envelope from its folder is an explicit clear_folder rather than "folder_id": null. An envelope is in at most one folder; new envelopes start unfoldered.

Every folder operation that names something the tree cannot hold (an unknown folder, a duplicate name among siblings, a move into the folder's own subtree, a sixth level) answers 422 folder-invalid with the rule in detail.

List and search

curl -s "https://app-staging.signenvoy.com/v1/documents?folder=c3d9...&q=acme&sort=activity" \
  -H "Authorization: Bearer $SENV_API_KEY"

• folder: envelopes in that folder only (not its subfolders).
• q: free text, up to 200 characters. It matches the envelope's title, its recipients' names and email addresses, and the name of the template it was created from. Words match as prefixes; quote a phrase to match it whole.
• status, sort, limit, offset: as before; q and folder combine with them.

The template name is recorded when the envelope is created. Renaming the template later does not change what older envelopes match on, so a search for the old name still finds them.

In the dashboard, the search field sits above the envelopes list and each result says what matched (title, recipient, or template). The folder tree appears in the list only once the workspace has a folder; a workspace that never creates one never sees it.

From the command line

senv doc list --folder <id> --q acme, and senv folder list|create|rename|move|rm wrap the calls above.