Topolo Docs Topolo Platform
Open workspace

Void envelope

Void a signature envelope so its outstanding signing links stop working and no further signature can be collected. A completed envelope cannot be voided; voiding is the only way to retract one already sent.

Outcome

Void a signature envelope so its outstanding signing links stop working and no further signature can be collected. A completed envelope cannot be voided; voiding is the only way to retract one already sent.

Before you start

  • Verify the environment, authenticated identity and specifically approved organization context.
  • The published application permission is workspace:write. Resolve and bind the exact canonical Sign workspace. A supplied id or organization membership alone grants no workspace access.
  • Session callers require read_write or admin workspace access. API-key resource binding is verified by Auth; never treat a caller-supplied header as an independent grant.
  • Approve the documented mutation and actual recipient/document targets before CLI --confirm or MCP confirm:true. A synthetic fixture authorizes no live agreement, notification or data deletion.

Discover the target

topolo whoami --json
topolo actions get app_topolo_sign.envelopes.void --detail --json
topolo resources topolo-sign --json
topolo workspaces list topolo-sign --json
  • Set SIGN_WORKSPACE_ID to the exact granted workspace returned by discovery.
  • Resolve envelopeId through envelopes.list/get or retain the exact creation response.

Request

POST /api/envelopes/{envelopeId}/void

Inspect and test this action. Save the reviewed input as payload.json. Supply resource context separately.

Input fields

FieldRequiredMeaningConstraints
envelopeIdRequiredExact envelope.id returned by creation or envelopes.list/get in this workspace.{"minLength":1}

Read the complete input schema.

Effects

  • Marks the envelope voided and stamps the time.
  • Outstanding signing links stop working, so no further signature can be collected.
  • Signatures already collected are retained in the audit trail; voiding does not erase them.
  • Voiding an already-voided envelope is a no-op and succeeds.

Interpret the response

Read $.envelope.id for the returned envelope identifier. An empty collection does not discover a target.

Call envelopes.get and confirm the status reads "voided". Confirm an outstanding signing link now refuses with signing_session_closed.

Inspect the success schema. CLI/MCP add their transport envelope; --detail requests the full CLI result. HTTP 204 contains no JSON payload.

Worked examples

Captured from the exported Sign Worker with the existing SQLite-backed D1 harness applying all core, envelope and audit migrations to one local database, in-memory R2 and synthetic Auth/workspace/archive/Notify transports. These examples prove local validation, persistence and artifact production. They do not prove separate deployed D1 topology, real recipient consent, provider delivery or a live signed agreement. All identities, signing links and documents are synthetic; replace identifiers through authorized discovery and never execute a fixture against a live organization. Binary download examples use the released SDK binary projection; tests Base64-decode and compare original bytes, lengths and server SHA-256 headers.

Supported request · Void the unsent local draft

Input · payload.json:

{
  "envelopeId": "e4fc2bcd-481c-450a-bdbd-fbbbc93f6865"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.void --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.void --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_sign.envelopes.void --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_sign.envelopes.void",
    "input": {
      "envelopeId": "e4fc2bcd-481c-450a-bdbd-fbbbc93f6865"
    },
    "resourceType": "workspace",
    "resourceId": "<exact granted id from discovery>",
    "confirm": true,
    "detail": true
  }
}

Captured exported Worker response · HTTP 200:

{
  "envelope": {
    "id": "e4fc2bcd-481c-450a-bdbd-fbbbc93f6865",
    "templateId": null,
    "title": "Disposable local draft",
    "subject": "Disposable local draft",
    "message": "",
    "status": "voided",
    "sourceApp": null,
    "sourceRef": null,
    "documentTitle": "Disposable local draft",
    "documentRef": null,
    "fieldSchemaVersion": 2,
    "fields": [],
    "fieldSchema": [],
    "source": null,
    "completedSha256": null,
    "correlationId": "sgn_8f7a0d29-cd77-4158-a40a-0f52804b6a89",
    "completedAt": null,
    "voidedAt": "2026-10-05T18:07:40.593Z",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-05T18:07:40.588Z",
    "updatedAt": "2026-10-05T18:07:40.593Z",
    "recipients": [],
    "auditEvents": [
      {
        "id": "d65bcc74-c5f0-4279-ac52-cf48040232c0",
        "envelopeId": "e4fc2bcd-481c-450a-bdbd-fbbbc93f6865",
        "recipientId": null,
        "eventType": "envelope.voided",
        "actorType": "user",
        "actorEmail": "operator@example.test",
        "metadata": {},
        "createdAt": "2026-10-05T18:07:40.594Z"
      },
      {
        "id": "bf675b77-d67d-4964-a1e2-43d8e90a24fa",
        "envelopeId": "e4fc2bcd-481c-450a-bdbd-fbbbc93f6865",
        "recipientId": null,
        "eventType": "envelope.created",
        "actorType": "user",
        "actorEmail": "operator@example.test",
        "metadata": {
          "recipientCount": 0,
          "fieldCount": 0,
          "sourceApp": null,
          "sourceRef": null
        },
        "createdAt": "2026-10-05T18:07:40.588Z"
      }
    ]
  }
}

HTTP 200. Call envelopes.get and confirm the status reads "voided". Confirm an outstanding signing link now refuses with signing_session_closed.

Refused request · HTTP 401

Input · payload.json:

{
  "envelopeId": "cb56a152-cb85-4388-ade9-ec54a5781830"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.void --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.void --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json

Captured exported Worker response · HTTP 401:

{
  "error": "Token validation failed"
}

HTTP 401. Resolve the exact refusal before retrying. This request is not a successful workflow.

Refused request · HTTP 403

Input · payload.json:

{
  "envelopeId": "cb56a152-cb85-4388-ade9-ec54a5781830"
}

CLI:

topolo actions validate app_topolo_sign.envelopes.void --data @payload.json --json
topolo actions plan app_topolo_sign.envelopes.void --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json

Captured exported Worker response · HTTP 403:

{
  "error": "This workspace requires read_write access",
  "code": "workspace_access_insufficient"
}

HTTP 403. Resolve the exact refusal before retrying. This request is not a successful workflow.

Verify the result

  • Call envelopes.get and confirm the status reads "voided".
  • Confirm an outstanding signing link now refuses with signing_session_closed.

Errors and recovery

  • organization_required (HTTP 403): The token carries no organization scope. Re-authenticate against the organization that owns the workspace and retry.
  • envelope_not_found (HTTP 404): No envelope in this workspace carries that id. Call envelopes.list and use an id from the response.
  • completed_envelope_cannot_be_voided (HTTP 409): Every recipient has already signed, so the agreement is executed and cannot be retracted here. Handle it as a commercial matter, not a Sign state change.
  • auth_error (HTTP 401): Reauthenticate in the same approved context before retrying.
  • workspace_access_insufficient (HTTP 403): Discover the actual workspace grant and obtain the documented required access; do not retry with a guessed workspace or broader organization.

Some existing refusals return a human message as error rather than a stable code; preserve the actual response, status and request id. Platform validation, authentication and resource checks can refuse before the handler.

Recovery boundary

A void cannot be undone and the links cannot be reissued on the same envelope. Create a fresh envelope and send it if signature is still needed.

  • Create envelope: Create a signature envelope as a DRAFT. Nothing is sent and no signer is contacted; the envelope stays editable until envelopes.send. Seed it from an active template, or supply the document, fields and recipients directly.
  • List Sign envelopes: List signature envelopes in this workspace with their status, recipients and document, plus a status summary, so you can find the envelopeId every other envelope action needs.

Evidence

Captured from the exported Sign Worker with the existing SQLite-backed D1 harness applying all core, envelope and audit migrations to one local database, in-memory R2 and synthetic Auth/workspace/archive/Notify transports. These examples prove local validation, persistence and artifact production. They do not prove separate deployed D1 topology, real recipient consent, provider delivery or a live signed agreement. All identities, signing links and documents are synthetic; replace identifiers through authorized discovery and never execute a fixture against a live organization. Binary download examples use the released SDK binary projection; tests Base64-decode and compare original bytes, lengths and server SHA-256 headers.