Envelopes

Create an envelope

Creates an envelope from exactly one source. The document branch accepts a ready unused documentId plus direct signers and fields. The template branch accepts templateId, exact role-keyed recipients, sender values, and optional field overrides, then snapshots the template's current version. The branches reject each other's keys.

send: true on either branch additionally requires envelopes:send, validates readiness before any write, and persists a durable send attempt in the creation transaction. Queue transport recovery happens asynchronously.

All shape and semantic failures are answered before partial resources are written. Honors Idempotency-Key for exact response replay.

post/envelopes

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/envelopes
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Makes this mutation retry-safe. 1 to 255 printable ASCII characters (0x20 to 0x7e), trimmed before use. The key is scoped to the workspace and the credential that sent it. Reusing it with a different method, path, or payload answers 422 idempotency_key_reuse. A completed attempt replays its stored status and body with an Idempotent-Replay: true response header; 5xx, 429, and non-JSON answers leave the key retryable. A concurrent request holding the 90 second lease answers 409 idempotency_in_progress. Records are retained 24 hours.

Request body

OR
OR

Example request

{
  "documentId": "Ku7bV2xQpL9mNr4sT1yZa",
  "subject": "Master Services Agreement",
  "message": "Please review and sign by Friday.",
  "signingOrder": "sequential",
  "expiresInDays": 30,
  "send": false,
  "signers": [
    {
      "key": "client",
      "name": "Dana Reyes",
      "email": "dana@acme.test",
      "order": 1
    },
    {
      "key": "counsel",
      "name": "Sam Okafor",
      "email": "sam@acme.test",
      "order": 2
    }
  ],
  "fields": [
    {
      "type": "signature",
      "name": "client_signature",
      "assignee": {
        "signerId": "client"
      },
      "pageIndex": 4,
      "xRatio": 0.12,
      "yRatio": 0.71,
      "widthRatio": 0.28,
      "heightRatio": 0.06
    },
    {
      "type": "date",
      "name": "effective_date",
      "assignee": {
        "signerId": "client"
      },
      "pageIndex": 4,
      "xRatio": 0.55,
      "yRatio": 0.71,
      "widthRatio": 0.18,
      "heightRatio": 0.04,
      "label": "Effective date"
    },
    {
      "type": "signature",
      "name": "counsel_signature",
      "assignee": {
        "signerId": "counsel"
      },
      "pageIndex": 4,
      "xRatio": 0.12,
      "yRatio": 0.82,
      "widthRatio": 0.28,
      "heightRatio": 0.06
    }
  ]
}

Response

The created envelope, with the public ids the server minted for its signers and fields. Status is sending when send: true committed durable send intent, otherwise draft.

Example response

{
  "data": {
    "id": "Jd3kR8sVqW2nX5cY7bLmP",
    "status": "draft",
    "subject": "Master Services Agreement",
    "signingOrder": "sequential",
    "template": null,
    "signers": [
      {
        "id": "Sg2wY6nT4qV8mR1xK9bDz",
        "name": "Dana Reyes",
        "email": "dana@acme.test",
        "status": "pending"
      },
      {
        "id": "Sg8pL3vB7nQ2xW6kT1yRc",
        "name": "Sam Okafor",
        "email": "sam@acme.test",
        "status": "pending"
      }
    ],
    "fields": [
      {
        "id": "Fd4tK9nW2vR7xB1sQ6mYe",
        "type": "signature",
        "pageIndex": 4
      },
      {
        "id": "Fd7yP2sV8mT3nX5kB9wLq",
        "type": "date",
        "pageIndex": 4
      },
      {
        "id": "Fd1cR6xN4qB8vT2mK7sZd",
        "type": "signature",
        "pageIndex": 4
      }
    ],
    "readiness": {
      "canSend": true,
      "issues": []
    },
    "send": {
      "requested": false,
      "status": "not_requested"
    },
    "expiresAt": "2026-09-20T09:19:58.000Z",
    "createdAt": "2026-08-21T09:19:58.000Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.