> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discard a draft envelope. ⚠️ Drafts only, and it cannot be undone.

> DELETES A DRAFT: an envelope created with `"send": false` (or saved as a draft in the dashboard) that has not been sent. Its recipients, its placed fields and the values filled in go with it. It is the same rule as the dashboard’s **Discard** button, and there is no list of discarded drafts to restore one from.

⚠️ **ONLY A DRAFT.** An envelope that has gone out is refused with `envelope_not_draft` and left exactly as it was. To withdraw a `sent` or `partially_signed` envelope, use `POST /api/v1/envelopes/{envelopeId}/void`, which keeps the envelope and its evidence and records why. A completed, declined, voided or expired envelope is finished and stays as it is.

Why a delete rather than a void: a draft has asked nobody to do anything, so there is nothing to withdraw and no history worth keeping. Voiding one would leave a permanent record of a document that was never sent.

**204, with no body.** The envelope is gone, so there is nothing true to return.

⚠️ A SECOND DELETE IS 404, NOT 204, as for webhooks. The act is idempotent — the end state is identical — so it takes no `Idempotency-Key` and a retry after a timeout is safe; but a 404 is the only answer that tells "I removed it" apart from "there was never one there". If you retried after a timeout and got 404, the first attempt deleted it. Another organisation’s envelope, and an id that is not a uuid, are the same 404.

NO WEBHOOK FIRES: a draft produces no events, and neither does its deletion. A `POST /api/v1/envelopes` retried with the `Idempotency-Key` that created the draft makes a new draft after this, rather than replaying the deleted one.

⚠️ A `vsk_test_` KEY MAY DISCARD ONLY A DRAFT A TEST KEY CREATED. Any envelope made in the dashboard or with a live key, draft or not, is refused with `test_key_cannot_discard` before its status is considered.



## OpenAPI

````yaml /openapi.json delete /api/v1/envelopes/{envelopeId}
openapi: 3.1.0
info:
  title: Vumasign API
  version: 0.2.0
  description: >-
    The Vumasign API. South African e-signature: templates, the addresses an

    integration writes values to, an idempotent send, and webhooks.


    **This document describes what exists today and nothing else.** It is not a

    roadmap, and there is deliberately no entry here for anything that has not

    shipped — a spec you can generate a client from and then discover was

    aspirational is worse than no spec at all.


    ## Authentication

        Authorization: Bearer vsk_live_…

    One header, one step. Keys are minted in Settings. `vsk_live_` and
    `vsk_test_`

    are different keys; the prefix is stored in clear so a leaked key is
    greppable

    and traceable to an organisation, while the secret is stored only as a hash.


    ## Errors


    Every refusal the API returns deliberately, at every status, is

    `{ "error": { "code", "message" } }`, and such a response is a failure **if

    and only if** it carries an `error` key — that test is correct even for a

    client that ignores the status line. An unexpected server failure may not
    have

    this shape: treat a 5xx without an `error` key as an `internal_error`, which

    is retryable. `code` is the

    contract and is stable forever; `message` is prose for a developer reading a

    log and may be reworded in any release.


    The root of this document carries **`x-error-codes`**: the closed enum, with

    `status`, `retryable`, `backoff`, `emitted` and `guidance` for each

    code. Branch on that rather than on our prose.


    ## Rate limits


    **600 requests a minute on any paid plan,

    60 on the free plan — and a test key

    gets the same number as a live one.** Per key, not per organisation, so a
    batch

    job and an interactive integration can be given a key each and neither can

    starve the other.


    The ceiling follows the PLAN rather than the kind of key, because the plan
    is

    what says whether this is production traffic or somebody evaluating us. On
    the

    API plan it is sized so that no honest workload meets it: a thousand
    envelopes

    with a status read each is two thousand requests, which is three and a half

    minutes rather than seventeen. The sandbox deliberately gets the *same*
    number

    rather than a larger one — an integration that passes in rehearsal is then
    an

    integration that passes live, and your `429` handling is exercised where

    meeting a `429` is free.


    Every successful authenticated response carries `RateLimit-Limit`,

    `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window

    closes, at most 60). Read them on your successes and you will never need to
    be

    refused. A 429 carries them too, and additionally carries `Retry-After`,
    which

    you should honour. A 401 carries none of them; a 403 may not, depending on

    whether it was decided before the request was counted. Each operation's

    responses say which others do.


    ⚠️ **A refused request still counts.** Retrying inside the window pushes the

    counter higher rather than holding it at the ceiling — which is why the
    backoff

    in `x-error-codes` is exponential and why `Retry-After` is worth reading

    rather than guessing at.


    ⚠️ The limits are **per minute**, and the window is fixed rather than
    sliding.

    Spending a whole window at the end of one minute and a whole window at the
    start

    of the next is possible; it is bounded at two windows' worth, which is a
    burst

    rather than an incident.


    ## Webhooks


    Register an endpoint with `POST /api/v1/webhooks`; the response carries the

    signing secret, **once**. The root of this document carries
    **`x-webhooks`**:

    the body we POST, the signature recipe (including the two mistakes that make
    a

    verifier look correct and be worthless), the published retry ladder, and the

    auto-disable rule. Read that before writing a receiver.


    ## What is not here yet


    No organisation-level email exists, so an auto-disabled webhook endpoint is

    discovered by polling rather than by being told. There is no way to change
    an

    envelope after it is created and before it is sent — `PATCH
    /v1/envelopes/{id}`

    is designed and not built — so a draft is created complete or not at all.
    Both

    are stated because a gap named is a gap somebody can plan around.


    ⚠️ **The rate limit above counts authenticated requests only.** A request

    carrying no key, or a key we cannot recognise, is refused before any counter
    is

    touched — a per-key ceiling cannot defend against a caller who has not
    presented

    a key, and pretending otherwise would be a promise we could not keep. That
    half

    belongs to the edge rather than to this API.


    (This section has twice described as missing something that now exists: the

    `uri` on every webhook body, which was `null` until

    `GET /api/v1/envelopes/{envelopeId}` gave it somewhere to point, and the
    rate

    limiter, which nothing enforced until the per-key ceiling above. Both were
    named

    here as gaps first, which is the point of naming them.)
servers:
  - url: https://app.vumasign.com
security:
  - ApiKey: []
tags:
  - name: Templates
    description: >-
      A template is a document with its signing roles and field placements
      authored once. Every envelope is made from one, or from a one-off pack.
  - name: Documents
    description: >-
      The pages of a template’s documents, served as PDF so that a client which
      has to show the paper can do so without rendering it itself.
  - name: Envelopes
    description: >-
      An envelope is one sending of a document to named people. Creating one is
      not sending it: a draft emails nobody until it is sent.
  - name: Webhooks
    description: >-
      Endpoints we POST signed events to when an envelope changes, with the
      health of each endpoint and a secret you can rotate without a gap.
  - name: Standing authorisations
    description: >-
      A grantor’s signed, brand-wide authority for your organisation to apply
      their signature to documents you send under that brand. Requested here; it
      takes effect only when the grantor signs the mandate and it is sealed. See
      /concepts/standing-authorisations.
  - name: Brands
    description: >-
      How your organisation presents itself to signers: name, colours, logo and
      the web origins allowed to frame its signing pages. Read here, and their
      embedding origins changed one at a time; everything else about a brand is
      managed in Settings → Brands. See /concepts/brands.
  - name: Specification
    description: >-
      This document, served without a credential so that anybody can read what
      the API does before they hold a key.
paths:
  /api/v1/envelopes/{envelopeId}:
    delete:
      tags:
        - Envelopes
      summary: Discard a draft envelope. ⚠️ Drafts only, and it cannot be undone.
      description: >-
        DELETES A DRAFT: an envelope created with `"send": false` (or saved as a
        draft in the dashboard) that has not been sent. Its recipients, its
        placed fields and the values filled in go with it. It is the same rule
        as the dashboard’s **Discard** button, and there is no list of discarded
        drafts to restore one from.


        ⚠️ **ONLY A DRAFT.** An envelope that has gone out is refused with
        `envelope_not_draft` and left exactly as it was. To withdraw a `sent` or
        `partially_signed` envelope, use `POST
        /api/v1/envelopes/{envelopeId}/void`, which keeps the envelope and its
        evidence and records why. A completed, declined, voided or expired
        envelope is finished and stays as it is.


        Why a delete rather than a void: a draft has asked nobody to do
        anything, so there is nothing to withdraw and no history worth keeping.
        Voiding one would leave a permanent record of a document that was never
        sent.


        **204, with no body.** The envelope is gone, so there is nothing true to
        return.


        ⚠️ A SECOND DELETE IS 404, NOT 204, as for webhooks. The act is
        idempotent — the end state is identical — so it takes no
        `Idempotency-Key` and a retry after a timeout is safe; but a 404 is the
        only answer that tells "I removed it" apart from "there was never one
        there". If you retried after a timeout and got 404, the first attempt
        deleted it. Another organisation’s envelope, and an id that is not a
        uuid, are the same 404.


        NO WEBHOOK FIRES: a draft produces no events, and neither does its
        deletion. A `POST /api/v1/envelopes` retried with the `Idempotency-Key`
        that created the draft makes a new draft after this, rather than
        replaying the deleted one.


        ⚠️ A `vsk_test_` KEY MAY DISCARD ONLY A DRAFT A TEST KEY CREATED. Any
        envelope made in the dashboard or with a live key, draft or not, is
        refused with `test_key_cannot_discard` before its status is considered.
      operationId: deleteEnvelope
      parameters:
        - name: envelopeId
          in: path
          required: true
          description: The draft envelope’s `id`, as returned when it was created.
          schema:
            type: string
            format: uuid
            examples:
              - 01960000-0000-4000-8000-0000000000e5
            description: An envelope id.
      responses:
        '204':
          description: >-
            Deleted. No body: the draft is gone, so there is nothing true to
            describe.
          headers:
            RateLimit-Limit:
              description: >-
                How many requests this key may make per minute: 600 on any paid
                plan and 60 on the free plan, the same in both environments. Per
                key, not per organisation — a second key has its own allowance.
                ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the
                database applied to this request, so it is right even when this
                description is out of date.
              schema:
                type: integer
                description: Requests permitted in the current minute.
            RateLimit-Remaining:
              description: >-
                How many of them are left, this one already counted. Zero on the
                request that is refused, and zero on every further request of
                that minute — ⚠️ a refused request still counts.
              schema:
                type: integer
                description: Requests remaining in the current minute.
            RateLimit-Reset:
              description: >-
                Seconds until the current minute closes and the allowance
                returns. At most 60, which is what makes the published
                exponential backoff converge in about six doublings rather than
                eleven.
              schema:
                type: integer
                description: Seconds until the window resets.
        '401':
          description: >-
            `unauthenticated` — The credential was absent, unreadable, unknown,
            wrong or revoked — this answer is deliberately identical for all of
            them, so it cannot be used to probe which keys exist. Retrying the
            same request changes nothing. Check the key in Settings or issue a
            new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '403':
          description: >-
            `forbidden` — The key is valid and the organisation’s plan does not
            grant what this operation does. Nothing about the credential needs
            to change, and it is deliberately MORE specific than 401 because the
            caller has already proved they hold the key. TWO SITUATIONS PRODUCE
            IT. (1) THE PLAN EXCLUDES THE OPERATION: `POST /api/v1/templates` on
            the Free plan, which does not include authoring templates. A
            template that already exists stays readable at `GET
            /api/v1/templates`; authoring one needs a plan that includes
            templates. (2) WE CANNOT ESTABLISH WHAT THE PLAN INCLUDES, on any
            operation, so nothing is granted. That one is ours rather than
            yours, an ordinary account does not meet it, and it means ask us.


            `insufficient_scope` — This key is scoped and does not hold the
            scope this operation requires — `x-required-scope` on the operation
            names it, and the `WWW-Authenticate` header on the refusal repeats
            it (RFC 6750 §3.1). ⚠️ Retrying cannot help until the key changes:
            an owner or admin edits its permissions under Settings → API keys,
            and the same key holds the new scope from its next request — no new
            key is needed. A key created before scopes existed carries an empty
            scope list, which means EVERY capability, so this refusal cannot
            reach an integration that was already working.


            `test_key_cannot_discard` — A `vsk_test_` key asked `DELETE
            /api/v1/envelopes/{envelopeId}` for an envelope that is not a
            sandbox envelope — one somebody made in the dashboard or with a live
            key, whether it is still a draft or has gone out. Deleting a draft
            cannot be undone, so a test key may discard only a draft a test key
            created. Nothing was deleted. If it is still a draft, discard it
            with a live key or from the dashboard. Retrying with the same key
            fails identically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '404':
          description: >-
            `not_found` — No such resource — or none this key’s organisation can
            see, or one that has been archived, or an id that is not a uuid.
            Those four are one answer on purpose: "it exists but is not yours"
            is itself a disclosure. Do not retry; check the id against the list
            endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '409':
          description: >-
            `envelope_not_draft` — Only a draft can be sent, and this envelope
            has already left draft — through this API, through the sender’s own
            Send button, or by being voided. ⚠️ THE EXACT OPPOSITE OF
            `envelope_not_sent`, and the two are not interchangeable: that one
            means the envelope has NOT gone out. An envelope never returns to
            draft, so this is terminal — read it with `GET
            /api/v1/envelopes/{envelopeId}` to see where it got to. ⚠️ If you
            were retrying a request that timed out, send the SAME
            `Idempotency-Key` instead and you will be told what the first
            attempt did. ⚠️ Discarding answers it too: `DELETE
            /api/v1/envelopes/{envelopeId}` deletes only a draft, so an envelope
            that has gone out is refused with this code and left as it was.
            Withdraw a `sent` or `partially_signed` one with `POST
            /api/v1/envelopes/{envelopeId}/void` instead; a finished one has
            nothing left to withdraw. The `message` says which state it is in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '429':
          description: >-
            `rate_limited` — This key has spent its minute. The limit is per KEY
            and per minute, and it follows your PLAN rather than the kind of key
            — 600 requests a minute on every paid plan, 60 on the free plan, and
            the sandbox gets the same number as production so that an
            integration which passes in rehearsal passes live. Every successful
            authenticated response, and this one, carries `RateLimit-Limit`,
            `RateLimit-Remaining` and `RateLimit-Reset` (seconds), so a client
            can slow down before it is made to. THREE OPERATIONS ALSO ANSWER IT
            FOR A REASON OF THEIR OWN. `POST /api/v1/envelopes/batches` costs
            one request per row and is refused WHOLE when its rows do not fit
            what is left of the key’s minute — `RateLimit-Remaining` says how
            many would. `GET
            /api/v1/envelopes/{envelopeId}/documents/{position}/draft` has its
            own per-envelope and per-organisation ceilings on renders each
            minute, and the `message` says which one refused; `POST
            /api/v1/templates/{templateId}/preview` shares the per-organisation
            one. There `Retry-After` is that ceiling’s, while the `RateLimit-*`
            headers still describe the key. `Retry-After` on this refusal is at
            most 60 and is read from the stored window rather than computed, so
            two of our instances refusing the same key quote the same instant.
            ⚠️ A REFUSED REQUEST STILL COUNTS: hammering a limit you have
            already exceeded pushes the counter higher rather than holding it.
            Honour `Retry-After`. If one key genuinely needs more throughput,
            issue a second one in Settings — the ceiling is a fairness and
            blast-radius control, not a commercial meter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
          headers:
            RateLimit-Limit:
              description: >-
                How many requests this key may make per minute: 600 on any paid
                plan and 60 on the free plan, the same in both environments. Per
                key, not per organisation — a second key has its own allowance.
                ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the
                database applied to this request, so it is right even when this
                description is out of date.
              schema:
                type: integer
                description: Requests permitted in the current minute.
            RateLimit-Remaining:
              description: >-
                How many of them are left, this one already counted. Zero on the
                request that is refused, and zero on every further request of
                that minute — ⚠️ a refused request still counts.
              schema:
                type: integer
                description: Requests remaining in the current minute.
            RateLimit-Reset:
              description: >-
                Seconds until the current minute closes and the allowance
                returns. At most 60, which is what makes the published
                exponential backoff converge in about six doublings rather than
                eleven.
              schema:
                type: integer
                description: Seconds until the window resets.
            Retry-After:
              description: >-
                Seconds to wait before retrying, from the stored end of the
                window. Always present on a 429, and never more than 60. On the
                per-key limit it equals `RateLimit-Reset`; a narrower limit,
                such as the draft render allowance, has a window of its own and
                may ask for a different wait. `x-error-codes` tells you to
                honour it; this is it.
              schema:
                type: integer
                description: Seconds to wait before retrying.
        '500':
          description: >-
            `internal_error` — Ours, not yours. ⚠️ RETRY WITH THE SAME
            `Idempotency-Key` YOU SENT THE FIRST TIME, on any operation that
            takes one — that is what makes a retry safe here, and sending a NEW
            key would create a second envelope or send the same one twice. The
            safe GETs in this document can be retried freely. (This entry used
            to say every operation here was a GET; the write endpoints have
            since shipped, and the reasoning moved with them.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
      security:
        - ApiKey: []
components:
  schemas:
    Error:
      type: object
      description: >-
        The body of every refusal the API returns deliberately, at every status,
        from every endpoint. Such a response is a failure if and only if it
        carries an `error` key — that test is correct even for a client that
        ignores the status line, which is a thing real clients do. An unexpected
        server failure may not have this shape: treat a 5xx without an `error`
        key as an `internal_error`, which is retryable.
      properties:
        error:
          type: object
          description: The refusal. Anything added in future is added INSIDE this object.
          properties:
            code:
              type: string
              description: >-
                A stable snake_case identifier that will never change meaning or
                spelling. This is the contract; branch on it. See
                `x-error-codes` at the root of this document for retry semantics
                per code.
              enum:
                - unauthenticated
                - forbidden
                - insufficient_scope
                - not_found
                - invalid_request
                - rate_limited
                - internal_error
                - service_unavailable
                - idempotency_key_required
                - idempotency_key_reused
                - request_in_progress
                - template_archived
                - template_unusable
                - template_has_no_fields
                - template_changed
                - template_document_not_omittable
                - precondition_required
                - field_unknown
                - naming_rule_broken
                - naming_run_not_ready
                - naming_run_failed
                - proposal_changed
                - decision_not_allowed
                - witness_is_permanent
                - recipient_role_unknown
                - recipient_role_missing
                - recipient_role_duplicated
                - recipient_step_partial
                - step_with_signing_mode
                - value_subject_unknown
                - value_address_unknown
                - value_not_writable
                - value_option_unknown
                - value_option_locked
                - value_selection_out_of_bounds
                - value_not_lockable
                - locked_answer_missing
                - locked_answer_unusable
                - cannot_be_drawn
                - send_allowance_exhausted
                - sms_allowance_exhausted
                - test_key_cannot_send
                - test_key_cannot_read_documents
                - test_key_cannot_edit_templates
                - document_too_complex
                - test_key_cannot_mint
                - test_key_cannot_extend
                - test_key_cannot_discard
                - test_key_cannot_void
                - webhook_url_invalid
                - webhook_events_invalid
                - webhook_brand_unknown
                - webhook_limit_reached
                - api_key_owner_removed
                - envelope_sender_removed
                - recipient_not_embedded
                - recipient_not_yet_turn
                - recipient_cannot_sign
                - envelope_not_sent
                - deadline_not_extendable
                - envelope_not_draft
                - brand_has_no_embed_origins
                - embed_origin_not_registered
                - recipient_cannot_be_embedded
                - recipient_verification_unavailable
                - recipient_mobile_unused
                - recipient_mobile_required
                - recipient_mobile_invalid
                - recipient_mobile_unsupported_country
                - recipient_verification_not_allowed
                - identity_check_requires_paid_plan
                - identity_check_not_live
                - recipient_identity_check_not_allowed
                - recipient_identity_routes_invalid
                - recipient_expected_id_invalid
                - batch_interrupted
                - brand_unknown
                - brand_is_archived
                - embed_origin_limit_reached
                - test_key_cannot_edit_brands
                - draft_not_available
                - standing_authorisations_not_enabled
                - authorisation_text_rejected
                - authorisation_validity_invalid
                - authorisation_not_revocable
                - authorisation_not_pending
                - authorisation_resend_limited
                - authorisation_not_renewable
                - authorisation_already_renewed
                - authorisation_unknown
                - authorisation_not_granted
                - authorisation_revoked
                - authorisation_expired
                - authorisation_not_yet_valid
                - authorisation_invalidated
                - authorisation_brand_mismatch
                - authorisation_environment_mismatch
                - authorisation_role_is_witness
                - authorisation_role_not_signing
                - authorisation_recipient_altered
                - authorisation_used_twice
                - authorisation_grantor_twice
                - authorisation_field_unsupported
                - authorisation_value_forbidden
                - value_for_left_out_role
                - authorisation_value_missing
                - authorisation_value_unlocked
                - authorisation_mark_too_small
                - authorisation_mark_unplaced
                - authorisation_mark_unavailable
                - authorisation_expires_during_batch
            message:
              type: string
              description: >-
                ⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the
                contract. It may be reworded in any release; anything that
                parses it is broken by design.
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        `Authorization: Bearer vsk_live_…`. Chosen over a bespoke `X-API-KEY`
        header because every client, proxy and log-redaction rule already knows
        this one. What a key may DO is its scopes — see `x-scopes` at the root
        of this document and `x-required-scope` on each operation. The scope
        list is not written here because OpenAPI reserves a requirement’s scope
        array for `oauth2` and `openIdConnect` and requires it to be empty for
        an `http` scheme.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.