> ## 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.

# Give a sent envelope a later deadline.

> MOVES `expires_at` LATER on an envelope that is out for signature. The envelope stays open until the new deadline and expires then, with `envelope.expired`, exactly as it would have at the old one.

⚠️ NOBODY IS EMAILED AND NO LINK IS REPLACED. Every signing link keeps the life it was given when it was sent, which was never longer than the old deadline. A signer whose link stops working at the old deadline can ask for a fresh one from the page the link opens, and that one runs to the new deadline; so do the links in reminders. A signer who already has a shorter-lived link is unaffected.

**Later, never earlier.** A deadline can only be extended: one that is not later than the current deadline, or a request for an envelope with no deadline, is `deadline_not_extendable`. The new deadline must also be within the bounds `POST /api/v1/envelopes` applies to `expires_at`: at least an hour from now, and at most a year from when the envelope was sent (`sent_at`), however many times it is extended. A deadline outside them is `invalid_request`.

**A test key extends only a sandbox envelope.** A `vsk_test_` key naming an envelope a test key did not create is `test_key_cannot_extend`.

**Only while it is still running.** A draft takes its deadline when it is created; a finished envelope has none left; and once a deadline has passed it cannot be extended, even before the envelope is marked `expired`. All three are `envelope_not_sent`.

The change is recorded in the envelope’s audit trail with both deadlines. No webhook event is sent for it: read the new deadline from the response, or from `GET /api/v1/envelopes/{envelopeId}`.

**200, not 201.** Nothing was created.

## The idempotency

`Idempotency-Key` IS REQUIRED. A retry under the same key replays the first 200 rather than being refused because the deadline is no longer later. THE NEW DEADLINE IS PART OF THE KEY’S FINGERPRINT: the same key sent with a different `expires_at` is `idempotency_key_reused`.



## OpenAPI

````yaml /openapi.json post /api/v1/envelopes/{envelopeId}/extend
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}/extend:
    post:
      tags:
        - Envelopes
      summary: Give a sent envelope a later deadline.
      description: >-
        MOVES `expires_at` LATER on an envelope that is out for signature. The
        envelope stays open until the new deadline and expires then, with
        `envelope.expired`, exactly as it would have at the old one.


        ⚠️ NOBODY IS EMAILED AND NO LINK IS REPLACED. Every signing link keeps
        the life it was given when it was sent, which was never longer than the
        old deadline. A signer whose link stops working at the old deadline can
        ask for a fresh one from the page the link opens, and that one runs to
        the new deadline; so do the links in reminders. A signer who already has
        a shorter-lived link is unaffected.


        **Later, never earlier.** A deadline can only be extended: one that is
        not later than the current deadline, or a request for an envelope with
        no deadline, is `deadline_not_extendable`. The new deadline must also be
        within the bounds `POST /api/v1/envelopes` applies to `expires_at`: at
        least an hour from now, and at most a year from when the envelope was
        sent (`sent_at`), however many times it is extended. A deadline outside
        them is `invalid_request`.


        **A test key extends only a sandbox envelope.** A `vsk_test_` key naming
        an envelope a test key did not create is `test_key_cannot_extend`.


        **Only while it is still running.** A draft takes its deadline when it
        is created; a finished envelope has none left; and once a deadline has
        passed it cannot be extended, even before the envelope is marked
        `expired`. All three are `envelope_not_sent`.


        The change is recorded in the envelope’s audit trail with both
        deadlines. No webhook event is sent for it: read the new deadline from
        the response, or from `GET /api/v1/envelopes/{envelopeId}`.


        **200, not 201.** Nothing was created.


        ## The idempotency


        `Idempotency-Key` IS REQUIRED. A retry under the same key replays the
        first 200 rather than being refused because the deadline is no longer
        later. THE NEW DEADLINE IS PART OF THE KEY’S FINGERPRINT: the same key
        sent with a different `expires_at` is `idempotency_key_reused`.
      operationId: extendEnvelopeDeadline
      parameters:
        - name: envelopeId
          in: path
          required: true
          description: The envelope to extend, as returned when it was created.
          schema:
            type: string
            format: uuid
            examples:
              - 01960000-0000-4000-8000-0000000000e5
            description: An envelope id.
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Any string that identifies this request; a UUID is the usual choice,
            and at most 255 characters. ⚠️ REQUIRED — see the note above.
          schema:
            type: string
            examples:
              - 01960000-0000-4000-8000-00000000ffff
            description: The caller’s own request identifier.
      requestBody:
        required: true
        description: The new deadline.
        content:
          application/json:
            schema:
              type: object
              description: The new deadline.
              properties:
                expires_at:
                  type: string
                  format: date-time
                  examples:
                    - '2026-09-30T21:59:59.000Z'
                  description: >-
                    THE NEW DEADLINE, as an absolute ISO 8601 instant with an
                    offset. Later than the envelope’s current `expires_at`, at
                    least an hour from now, and at most a year from when the
                    envelope was sent.
              required:
                - expires_at
            examples:
              example:
                summary: Two more weeks
                value:
                  expires_at: '2026-09-30T21:59:59.000Z'
      responses:
        '200':
          description: >-
            The envelope, with its new `expires_at`. Everything else is as it
            was.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
                description: The envelope, as it now stands.
              examples:
                example:
                  summary: The envelope, with its later deadline
                  value:
                    id: 01960000-0000-4000-8000-0000000000e5
                    status: sent
                    template_id: 01960000-0000-4000-8000-0000000007e1
                    title: Employment contract
                    reference: hire-2026-0917
                    created_at: '2026-09-02T09:00:00.000Z'
                    sent_at: '2026-09-02T09:05:00.000Z'
                    expires_at: '2026-09-30T21:59:59.000Z'
                    recipients:
                      - id: 01960000-0000-4000-8000-00000000005e
                        role: Employee
                        name: Thandi Mokoena
                        email: thandi@example.test
                        routing_type: sign
                        status: sent
                        invitation_delivered: true
                        embedded: false
                        delegates_stay_embedded: false
                        external_ref: null
                        verification_method: email_code
                        mobile: null
                        identity_check: null
                        completion_basis: null
                        standing_authorisation: null
                    subjects: []
                    roles_left_out: []
          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.
        '400':
          description: >-
            `invalid_request` — The request is malformed, or breaks a rule about
            its own shape: a body that is not JSON or does not match the
            operation’s schema (a missing or mistyped property, a value out of
            range), a document that is not a PDF or a Word file we can read, a
            text tag that cannot be placed, an `Idempotency-Key` that is present
            but not a valid key, a query parameter outside its range, or a
            cursor that names nothing. The `message` says which, and for a body
            names the property path (`recipients[0].email`) — there is no
            separate `param` field. Fix the request; retrying it unchanged will
            fail identically.


            `idempotency_key_required` — Send `Idempotency-Key: <uuid>` — this
            operation takes one and the request carried none. A distinct code
            from `invalid_request` because the remedy is to ADD a header, and an
            integrator reading it in a log should not have to work that out. (A
            key that is present but malformed is `invalid_request`, and its
            `message` names the header.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '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_extend` — A `vsk_test_` key asked `POST
            /api/v1/envelopes/{envelopeId}/extend` for an envelope that is not a
            sandbox envelope. A deadline decides how long a document stays
            signable, and on a live envelope that document is binding, so a test
            key may extend only an envelope a test key created. The deadline was
            not changed and nothing was recorded. Extend this one with a live
            key, or rehearse on an envelope created with your test key. 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: >-
            `idempotency_key_reused` — This key was already used for a DIFFERENT
            request. ⚠️ The request itself may be perfectly valid — what
            conflicts is the key against state we already hold, which is what
            409 means and why it is not a 400. Mint a new key. Do not retry with
            this one; it will conflict forever.


            `request_in_progress` — A request carrying this key has not
            finished. We deliberately do not block waiting for it — that would
            hold a connection across a send that calls an email provider N
            times. Retry the identical request; when the first one lands you
            will get its result, replayed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                description: The refusal.
        '422':
          description: >-
            `envelope_not_sent` — This operation needs an envelope that is out
            for signing, and this one is not: it is still a draft, or it is
            finished (completed, declined, voided or expired). Three operations
            answer it. Minting a signing URL: a draft has not been sent to
            anybody — create it with `"send": true`, or send it first. Voiding:
            a draft has nothing to withdraw, because nobody has been asked to
            sign it — discard it with `DELETE /api/v1/envelopes/{envelopeId}`
            instead — and a finished envelope cannot be withdrawn. Extending a
            deadline: a draft takes its deadline when it is created, and a
            finished envelope has none left to move. The `message` says which
            state it is in. ⚠️ Minting and extending also answer it for an
            envelope whose deadline has passed while it still shows an open
            status: the expiry sweep has not marked it `expired` yet, but it is
            finished all the same. ⚠️ A `vsk_test_` key CAN reach an open
            envelope: it may send one when everybody it would email is a member
            of your organisation or a confirmed test recipient, and an
            `"embedded": true` recipient is never emailed, so is never checked.
            A test key meets this code for the same reasons a live key does —
            most often, a draft that was never sent — except that on an envelope
            a test key did not create, minting is refused first with
            `test_key_cannot_mint`, extending with `test_key_cannot_extend` and
            voiding with `test_key_cannot_void`.


            `deadline_not_extendable` — The envelope is out for signing, but its
            deadline cannot be moved to the one you asked for: it has no
            deadline at all, so there is nothing to extend, or `expires_at` is
            not later than the deadline it has now. A deadline can be extended,
            never shortened. The `message` says which, and gives the current
            deadline; read it from `GET /api/v1/envelopes/{envelopeId}` and ask
            for a later one.
          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:
    Envelope:
      type: object
      description: 'An envelope: a template instantiated with real people and real values.'
      properties:
        id:
          type: string
          format: uuid
          description: The envelope’s id. A bare uuid.
        status:
          type: string
          description: >-
            `draft` or `sent` from this endpoint. Later states arrive as people
            act.
        template_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The template this was made from, or `null` when there was none — an
            envelope created by `POST /api/v1/envelopes/one-off` carries the
            document itself and never had a template. Branch on `null`, never on
            the empty string.
        title:
          type: string
          description: >-
            What the signers see naming the document. Defaults to the template’s
            name.
        reference:
          type:
            - string
            - 'null'
          examples:
            - hire-2026-0917
          description: >-
            The `reference` you set when you created it, in Unicode NFC, or
            `null`. Not unique, and never changed after creation.
        created_at:
          type: string
          format: date-time
          description: ISO 8601, UTC.
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601, UTC. Null while it is a draft.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            ISO 8601, UTC. Null when this envelope has no deadline, which is the
            default. Read back from the stored value rather than echoed, so an
            offset you sent comes back as the same instant in UTC.
        recipients:
          type: array
          description: In routing order.
          items:
            $ref: '#/components/schemas/EnvelopeRecipient'
            description: One recipient.
        subjects:
          type: array
          description: >-
            Who the envelope is about, such as a spouse or a dependant, in the
            order they were declared: the `subject` a value names. A one-off’s
            come from setting it up in the editor; an envelope made from a
            template has its template’s. Empty when the envelope is about nobody
            in particular.
          items:
            $ref: '#/components/schemas/EnvelopeSubject'
            description: One person the envelope is about.
        roles_left_out:
          type: array
          description: >-
            The optional roles this envelope was sent without (`Role.presence`
            is `optional` on its template, and nobody was named for the role: no
            recipient in the request, or only an empty slot on a draft prepared
            in the dashboard). Each was left out when the envelope was sent,
            with every field it held, and the sealed certificate lists it as not
            on the envelope. Only a role that held fields is listed: one with
            none has nothing to leave out. Empty before the envelope is sent and
            for a one-off.
          items:
            type: object
            description: One optional role the envelope was sent without.
            required:
              - role
              - kind
            properties:
              role:
                type: string
                examples:
                  - Surety
                description: The role’s name.
              kind:
                type: string
                enum:
                  - party
                  - witness
                description: The role’s kind when it was left out.
      required:
        - id
        - status
        - template_id
        - title
        - reference
        - created_at
        - sent_at
        - expires_at
        - recipients
        - subjects
        - roles_left_out
    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
    EnvelopeRecipient:
      type: object
      description: One recipient of an envelope, as it stands.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            This recipient. Published where a template ROLE’s id deliberately is
            not, because a recipient has no natural key — one person may hold
            two roles and two people may hold one.
        role:
          type: string
          description: The template role they were given.
        name:
          type:
            - string
            - 'null'
          description: >-
            As stored, after normalisation. `null` only while the envelope is a
            `draft` and nobody has been named for this role yet (a draft
            prepared in the dashboard); every sent recipient has a name.
        email:
          type:
            - string
            - 'null'
          format: email
          description: >-
            As stored, after normalisation. `null` only while the envelope is a
            `draft` and nobody has been named for this role yet; every sent
            recipient has an address. A copied-in recipient with no address when
            the envelope is sent is left off it.
        routing_type:
          type: string
          enum:
            - sign
            - approve
            - cc
          description: >-
            ⚠️ FROM THE TEMPLATE, NEVER FROM THE REQUEST. Whether a role signs,
            approves or is copied in is part of the layout (§3), and a caller
            who could override it could send a document whose signature boxes
            nobody will ever be asked to fill.
        status:
          type: string
          description: >-
            `recipients.status` verbatim. ⚠️ `pending` AFTER A SUCCESSFUL SEND
            IS NORMAL: an envelope in steps invites only its lowest unfinished
            step and holds the rest back until that step is finished.
        invitation_delivered:
          type:
            - boolean
            - 'null'
          description: >-
            Whether the email provider reports the invitation as DELIVERED.
            `null` when none was attempted — a draft, a `cc`, an embedded
            recipient, or a position held back.


            ⚠️ ON A READ, THIS NO LONGER ANSWERS `true` AS SOON AS THE SEND
            RETURNS, and it used to. Accepting a message and delivering it are
            different events: we now record delivery only when the provider
            tells us it happened, on the provider's clock. A just-sent
            invitation therefore reads `false` on `GET /api/v1/envelopes/{id}`
            and turns `true` seconds to minutes later.


            ⚠️ THE ONE EXCEPTION IS THE RESPONSE TO `POST .../send` ITSELF,
            where `true` means the provider ACCEPTED the message — the only
            thing anybody knows while the send is still running. That
            operation’s response description says so at length. The same
            recipient can therefore read `true` from the send and `false` from a
            read a second later; the read is the one to decide from.


            ⚠️ `false` IS NOT A BOUNCE. It covers both "the provider refused the
            send" and "we have not been told yet", and you cannot tell those
            apart from this field — do not surface it to a human as a failure.
            `null` is the only value that has never changed meaning: nothing was
            attempted.
        embedded:
          type: boolean
          description: >-
            Whether this recipient is reached by a minted signing URL instead of
            by email. ⚠️ RETURNED HERE PRECISELY BECAUSE DocuSign DOES NOT
            RETURN THEIRS: `clientUserId` is absent from their list endpoints,
            so an integrator who lost their own record of which recipients were
            embedded has no way to ask. When this is true,
            `invitation_delivered` is always `null` — nothing was attempted, and
            nothing was meant to be.
        delegates_stay_embedded:
          type: boolean
          description: >-
            Whether a person this recipient delegates to is kept embedded. Only
            ever `true` beside `embedded: true`: you sent it at creation, or
            this recipient took the place of one who had it (their delegate, a
            correction, or a new person in the same draft slot). When it is
            `false`, the delegate of an embedded recipient is emailed a signing
            link like any other recipient, and appears here as a new recipient
            with `embedded: false`.
        external_ref:
          type:
            - string
            - 'null'
          description: >-
            Whatever you supplied at creation, normalised to Unicode NFC, or
            `null`: compare it in NFC, not byte for byte. Opaque to us and
            joined on by nothing — it is here so a webhook or this response can
            be matched to your own record of the same human without a side
            table.
        verification_method:
          type: string
          enum:
            - none
            - email_code
            - mobile_code
            - identity_check
          description: >-
            What this recipient must prove before the document opens, read back
            from the recipient as it was created — `none` when the request did
            not say, and `mobile_code` for a recipient created with the
            deprecated `sms_code`. Fixed once the envelope is sent. ⚠️ IT SAYS
            WHAT WAS ASKED, NOT WHETHER THEY HAVE DONE IT: whether a code was
            entered is in the audit trail and on the certificate of completion.
        mobile:
          type:
            - string
            - 'null'
          examples:
            - '+27821234567'
          description: >-
            The mobile a `mobile_code` recipient’s code is sent to, in E.164 as
            stored (`+27821234567`), returned in full because it is your own
            data. `null` for every other method. Fixed once the envelope is
            sent: a wrong number is fixed by correcting the recipient.
        identity_check:
          type:
            - object
            - 'null'
          description: >-
            On a recipient asked for an identity check, what was asked: the
            documents they may use (`routes`) and the ID you said to expect, as
            its kind, its last digits behind bullets (`masked`) and a passport’s
            country — ⚠️ never the number, which is not stored — and, once the
            check has finished, how it ended (`outcome`). `null` for every other
            method.
          properties:
            routes:
              type: string
              enum:
                - either
                - sa_id
                - passport
              description: The documents they may use.
            expected_id:
              type:
                - object
                - 'null'
              description: The ID you said to expect, masked, or `null` when you gave none.
              properties:
                kind:
                  type: string
                  enum:
                    - sa_id
                    - passport
                  description: An SA ID number, or a passport number.
                masked:
                  type: string
                  examples:
                    - •••••••••0087
                  description: Its last digits behind bullets.
                country:
                  type:
                    - string
                    - 'null'
                  description: >-
                    A passport’s issuing country (ISO 3166 alpha-3); `null` for
                    an SA ID.
              required:
                - kind
                - masked
                - country
            outcome:
              type:
                - object
                - 'null'
              description: >-
                `null` until the check finishes; then how it ended, from the
                same record the certificate of completion is built from.
                `recipient.identity_verified` and
                `recipient.identity_check_failed` are the webhooks that say
                when. ⚠️ Never the ID or passport number, a score, a photo or
                the name on the document: only the masked number and the name
                verdict.
              properties:
                status:
                  type: string
                  enum:
                    - passed
                    - failed
                  description: '`passed`, or `failed` when the check cannot finish.'
                reason:
                  type:
                    - string
                    - 'null'
                  enum:
                    - attempts_exhausted
                    - id_mismatch
                    - cannot_use_camera
                    - null
                  description: >-
                    On `failed`, why: the same `reason` the
                    `recipient.identity_check_failed` webhook carries. `null` on
                    `passed`.
                completed_at:
                  type: string
                  format: date-time
                  description: When it passed or failed.
                route:
                  type:
                    - string
                    - 'null'
                  enum:
                    - sa_id
                    - passport
                    - null
                  description: The route the signer took. `null` on `failed`.
                document:
                  type:
                    - object
                    - 'null'
                  description: The document checked, masked. `null` on `failed`.
                  properties:
                    kind:
                      type: string
                      enum:
                        - smart_id_card
                        - id_book
                        - passport
                      description: A Smart ID card, a green ID book, or a passport.
                    masked:
                      type: string
                      examples:
                        - •••••••••0087
                      description: Its number’s last digits behind bullets.
                    country:
                      type:
                        - string
                        - 'null'
                      description: >-
                        A passport’s issuing country (ISO 3166 alpha-3); `null`
                        for an SA ID.
                  required:
                    - kind
                    - masked
                    - country
                expected_id_matched:
                  type:
                    - boolean
                    - 'null'
                  description: >-
                    `true` when you gave an `expected_id` of this route’s kind
                    and the document’s number matched it; `false` when you gave
                    none for this route. `null` on `failed` (a number that did
                    not match fails as `id_mismatch`).
                name_match:
                  type:
                    - string
                    - 'null'
                  enum:
                    - match
                    - partial
                    - mismatch
                    - null
                  description: >-
                    The name on the document against the recipient’s `name`.
                    Names are compared ignoring case, accents, spacing,
                    apostrophes and full stops, with a hyphen read as a space,
                    word by word and in any order. `match`: the surname on the
                    document is in the name you gave, and one side’s given names
                    are all in the other’s (a second name missing on either side
                    is fine). `partial`: the surname matches but a given name
                    differs only by an initial (J for John) or is missing, or
                    the given names match and the surname differs (a maiden or
                    married name). `mismatch`: anything else. `null`: no usable
                    name on the document, or none on the recipient. A name never
                    fails the check. `null` on `failed`.
                provider:
                  type: string
                  enum:
                    - verifynow
                  description: Who checked it.
                provider_reference:
                  type:
                    - string
                    - 'null'
                  description: >-
                    VerifyNow’s reference for the face match, which the
                    certificate prints; `null` when it gave none, and on
                    `failed`.
                test_mode:
                  type: boolean
                  description: >-
                    A test envelope’s check: VerifyNow’s sandbox returned a
                    sample result.
              required:
                - status
                - reason
                - completed_at
                - route
                - document
                - expected_id_matched
                - name_match
                - provider
                - provider_reference
                - test_mode
          required:
            - routes
            - expected_id
            - outcome
        completion_basis:
          type:
            - string
            - 'null'
          enum:
            - session
            - standing_authorisation
            - null
          description: >-
            How this recipient completed: `session` for a person who signed or
            approved themselves, `standing_authorisation` for a role pre-signed
            when the document was sent, under a standing authorisation. `null`
            until they complete — including a draft’s pre-signed role, which
            completes only when the envelope is sent.
        standing_authorisation:
          type:
            - object
            - 'null'
          description: >-
            The standing authorisation named on this role, or `null` for a
            person. Present from the draft on. The grantor named on it is never
            emailed about the document.
          properties:
            id:
              type: string
              format: uuid
              description: The authorisation.
            number:
              type: string
              examples:
                - SA-0012
              description: Its number, as printed.
            witness:
              type: boolean
              description: >-
                Whether the mark was applied as a WITNESS’s: the role is a
                witness, the authorisation was granted for witness use, and the
                document, its certificate and its verification page say the
                witness was not present. `false` until the send applies it, and
                always for a party.
          required:
            - id
            - number
            - witness
      required:
        - id
        - role
        - name
        - email
        - routing_type
        - status
        - invitation_delivered
        - embedded
        - delegates_stay_embedded
        - external_ref
        - verification_method
        - mobile
        - identity_check
        - completion_basis
        - standing_authorisation
    EnvelopeSubject:
      type: object
      description: One person the envelope is about.
      properties:
        key:
          type: string
          examples:
            - spouse
          description: The key a value’s `subject` names.
        label:
          type: string
          examples:
            - Spouse
          description: What a person reads.
        presence:
          type: string
          enum:
            - required
            - conditional
          description: '`required`: always on this envelope. `conditional`: may be left out.'
        present:
          type: boolean
          description: >-
            Whether this envelope has this person. When `false`, their boxes are
            hidden from the signer and are not required. A `conditional` person
            may still be switched on or off by the signer. While the signer is
            still to be asked (`awaiting_signer`), this is `false`, which is
            what the signer sees until they answer.
        awaiting_signer:
          type: boolean
          description: >-
            `true` while the signer is still to be asked whether this person is
            on the form: the sender chose Ask the signer, and nobody has
            answered yet. `present` is then `false`. Read the two together to
            tell a person left out from one not answered yet. Always `false` for
            a `required` person.
        starts_as:
          type: string
          enum:
            - ask
            - present
            - absent
          description: >-
            The sender’s choice for a `conditional` person: `ask` (the signer is
            asked), `present` (Include) or `absent` (Leave out). Fixed once the
            envelope is sent, while `present` is the fact now and can change.
            Read it with `present`: an envelope made before the sender could
            choose reads `absent`. Not meaningful for a `required` person.
      required:
        - key
        - label
        - presence
        - present
        - awaiting_signer
        - starts_as
  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.