Envelopes

Create an incomplete draft envelope

Creates a versioned draft from a ready unused document. Signers and fields may both be empty. The response is the canonical editable snapshot and includes computed readiness. The existing createEnvelope operation remains the one-shot compatibility path. Honors Idempotency-Key.

post/envelopes/drafts

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/envelopes/drafts
  • 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

documentIdstring required
subjectstring
messagestring nullable
signingOrder'parallel' | 'sequential'
emailVerificationboolean
expiresInDaysinteger

Example request

{
  "signers": [
    {
      "name": "Dana Reyes",
      "email": "dana@acme.test",
      "role": "signer",
      "phone": "+1 (415) 555-0100"
    }
  ],
  "fields": [
    {
      "type": "signature",
      "assignee": {
        "signerId": "client"
      },
      "pageIndex": 4,
      "xRatio": 0.12,
      "yRatio": 0.71,
      "widthRatio": 0.28,
      "heightRatio": 0.06,
      "required": true,
      "label": "Effective date",
      "detectionSource": "agent",
      "detectionConfidence": 0.94,
      "detectionReason": "Signature line beneath \"Client signature\" on page 5"
    }
  ],
  "cc": [
    {
      "name": "Wren Watcher",
      "email": "wren@acme.test"
    }
  ]
}

Response

The new editable draft at editor version 1.

Example response

{
  "data": {
    "signers": [
      {
        "role": "signer"
      }
    ],
    "fields": [
      {
        "type": "signature",
        "assignee": {
          "signerId": "client"
        },
        "pageIndex": 4,
        "xRatio": 0.12,
        "yRatio": 0.71,
        "widthRatio": 0.28,
        "heightRatio": 0.06,
        "required": true,
        "label": "Effective date",
        "detectionSource": "agent",
        "detectionConfidence": 0.94,
        "detectionReason": "Signature line beneath \"Client signature\" on page 5"
      }
    ],
    "cc": [
      {
        "id": "Qm5tW8xZ1aB4cD7eF0gHj",
        "name": "Wren Watcher",
        "email": "wren@acme.test"
      }
    ],
    "creditCost": 5,
    "creditLines": [
      {
        "kind": "signer",
        "quantity": 3,
        "unitCredits": 1,
        "credits": 3
      }
    ]
  }
}

Changes

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