mcp

Send a document for e-signature. Accepts PDF as base64, recipients, and field placement. Sandbox keys (sk_test_) send immediately (watermarked test mail). LIVE keys create a DRAFT and return it for human review unless confirm: true — nothing is emailed until confirmed. Field placement: page+x+y (percent, top-left origin) OR an anchor string, not both. After everyone signs, retrieve the sealed PDF with swiftsign_download_signed_pdf.

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "Email subject / document title"
    },
    "message": {
      "description": "Optional message to include",
      "type": "string"
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Document filename (e.g. 'contract.pdf')"
          },
          "base64": {
            "type": "string",
            "description": "Base64-encoded PDF content"
          }
        },
        "required": [
          "name",
          "base64"
        ]
      },
      "description": "PDF documents to send"
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Recipient full name"
          },
          "email": {
            "type": "string",
            "description": "Recipient email address"
          },
          "role": {
            "default": "SIGNER",
            "type": "string",
            "enum": [
              "SIGNER",
              "CC"
            ]
          },
          "routingOrder": {
            "default": 1,
            "description": "Signing order (1 = first)",
            "type": "number"
          }
        },
        "required": [
          "name",
          "email"
        ]
      },
      "description": "People who need to sign or receive a copy"
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "recipientIndex": {
            "type": "number",
            "description": "Index into recipients array (0-based)"
          },
          "type": {
            "type": "string",
            "enum": [
              "SIGNATURE",
              "NAME",
              "DATE",
              "TEXT",
              "INITIALS",
              "CHECKBOX",
              "RADIO",
              "DROPDOWN",
              "ATTACHMENT"
            ],
            "description": "Field type"
          },
          "document": {
            "default": 0,
            "description": "Document index (0-based)",
            "type": "number"
          },
          "page": {
            "type": "number",
            "description": "Page number (1-based). Ignored when anchor resolves."
          },
          "x": {
            "type": "number",
            "description": "X position, percent 0-100 of page width, top-left origin"
          },
          "y": {
            "type": "number",
            "description": "Y position, percent 0-100 of page height, top-left origin"
          },
          "width": {
            "description": "Field width (percent)",
            "type": "number"
          },
          "height": {
            "description": "Field height (percent)",
            "type": "number"
          },
          "anchor": {
            "description": "Anchor text to search in the PDF. Use anchor OR page+x+y, not both.",
            "type": "string"
          },
          "yOffset": {
            "description": "Y offset from anchor (percent)",
            "type": "number"
          },
          "options": {
            "description": "Choices for RADIO / DROPDOWN fields",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "recipientIndex",
          "type",
          "page",
          "x",
          "y"
        ]
      },
      "description": "Signing fields to place on documents"
    },
    "confirm": {
      "description": "Set true to dispatch immediately on a LIVE key (sk_live_/sk_oat_). Without it, live envelopes are created as DRAFT and returned for human review before anything is emailed. Test keys (sk_test_) always send immediately (sandbox, watermarked).",
      "type": "boolean"
    }
  },
  "required": [
    "subject",
    "documents",
    "recipients",
    "fields"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Dispatch a DRAFT envelope — use after a human has reviewed an envelope that swiftsign_send_envelope or swiftsign_send_from_template returned as draft_pending_confirmation. This emails the signers. Does NOT work on envelopes already SENT/COMPLETED/VOIDED.

{
  "type": "object",
  "properties": {
    "envelopeId": {
      "type": "string",
      "description": "The DRAFT envelope ID to dispatch"
    }
  },
  "required": [
    "envelopeId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Send an envelope from a saved template by assigning signers to roles. Sandbox keys (sk_test_) send immediately; LIVE keys create a DRAFT for human review unless confirm: true — nothing is emailed until confirmed.

{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "description": "The template ID to send from"
    },
    "roleAssignments": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Signer full name"
          },
          "email": {
            "type": "string",
            "description": "Signer email address"
          }
        },
        "required": [
          "name",
          "email"
        ]
      },
      "description": "Map of template role name → signer { name, email }"
    },
    "subject": {
      "description": "Email subject / document title",
      "type": "string"
    },
    "message": {
      "description": "Optional message to include",
      "type": "string"
    },
    "confirm": {
      "description": "Set true to dispatch immediately on a LIVE key (sk_live_/sk_oat_). Without it, live envelopes are created as DRAFT and returned for human review before anything is emailed. Test keys (sk_test_) always send immediately (sandbox, watermarked).",
      "type": "boolean"
    }
  },
  "required": [
    "templateId",
    "roleAssignments"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check the status of an envelope — who signed, who hasn't, download links. Works in both sandbox (sk_test_ keys) and live.

{
  "type": "object",
  "properties": {
    "envelopeId": {
      "type": "string",
      "description": "The envelope ID to check"
    }
  },
  "required": [
    "envelopeId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List envelopes (sent documents) with their status. Scoped to your key's mode — sandbox (sk_test_) keys see test envelopes, live keys see live.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel/void an envelope that hasn't been completed yet. Signers can no longer sign a voided envelope. Works in both sandbox (sk_test_ keys) and live.

{
  "type": "object",
  "properties": {
    "envelopeId": {
      "type": "string",
      "description": "The envelope ID to void"
    }
  },
  "required": [
    "envelopeId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Download the completed, sealed PDF (or its Certificate of Completion) for an envelope. Only works once status is COMPLETED — run swiftsign_check_status first. Does NOT work on DRAFT or SENT envelopes; nothing has been signed yet on those.

{
  "type": "object",
  "properties": {
    "envelopeId": {
      "type": "string",
      "description": "The envelope ID (must be COMPLETED)"
    },
    "outputPath": {
      "description": "Where to save the file (default: ./swiftsign-<id>.pdf). Ignored on the hosted endpoint, which returns base64.",
      "type": "string"
    },
    "document": {
      "description": "Which document to download when an envelope has several (0-based, default 0)",
      "type": "number"
    },
    "certificate": {
      "description": "If true, download the Certificate of Completion (audit trail) instead of the signed document",
      "type": "boolean"
    }
  },
  "required": [
    "envelopeId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Initiate the upgrade to PRO ($15/mo flat). Returns a Stripe checkout_url that a human opens once to add a card — agents cannot complete the payment themselves. Moves the account from sandbox (sk_test_) to live sends. Returns status 'updated' if already on the plan.

{
  "type": "object",
  "properties": {
    "plan": {
      "description": "Plan to upgrade to (default PRO)",
      "type": "string",
      "const": "PRO"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Mint a short-lived embedded signing URL for a recipient (30-minute expiry). Returns a url to embed plus its expiresAt. The envelope must already be SENT. Works in both sandbox (sk_test_ keys) and live.

{
  "type": "object",
  "properties": {
    "envelopeId": {
      "type": "string",
      "description": "The envelope ID"
    },
    "recipientId": {
      "type": "string",
      "description": "The recipient ID within that envelope"
    },
    "returnUrl": {
      "description": "URL to redirect the signer to after they finish",
      "type": "string"
    }
  },
  "required": [
    "envelopeId",
    "recipientId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List your saved templates. Scoped to your key's mode — sandbox (sk_test_) keys see test templates, live keys see live.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}