API & developers

Build with the same primitives we use.

The VG·Sign REST API creates, sends and tracks envelopes with a workspace token. It is included on Pro, Team and Enterprise, and the full reference is on the API page.

On this page

Get a workspace token

  1. As the workspace owner, open Settings, Integrations.
  2. Under API access, click Generate token.
  3. Copy the token straight away. It starts with vgs_live_ and is shown once, because we keep only a hash of it.

A workspace has one token. Rotate token replaces it and the old one stops working at once; Revoke removes it. On Free the button is replaced by “The API is included on Pro, Team and Enterprise.” If a paid workspace moves to Free, its token is paused and calls answer 403 plan_required until you upgrade again.

Your first request

Send the token as a bearer token. This call lists your envelopes, newest first:

curl https://vg-sign.com/api/v1/envelopes \
  -H "Authorization: Bearer vgs_live_…"

The reply holds an envelopes array with total, limit, offset and has_more. Filter with ?status=completed or your own external_ref; limit goes up to 100.

Each token may make 600 requests a minute. Past that you get a 429 with a Retry-After header. Every endpoint is described in OpenAPI 3.1 at /api/v1/openapi.json, which most client generators can read.

Place fields over the API

POST /api/v1/envelopes takes multipart/form-data: a metadata part holding JSON, and one files part per PDF. Put the recipients and a fields array in that JSON. Each field is one box on one page for one recipient:

{
  "recipient_email": "client@example.com",
  "document": "contract.pdf",
  "type": "signature",
  "page": 1,
  "x": 0.12, "y": 0.60,
  "width": 0.30, "height": 0.07
}
  • Coordinates are fractions of the page, from 0 to 1, measured from the top-left corner.
  • document is a file name from documents; leave it out when there is only one signable document.
  • type is signature, initials, full_name, text, date, time, checkbox, strikethrough, multiline, dropdown, radio or attachment. required defaults to true, and every signer needs at least one required field.
  • A dropdown takes options (2 to 50) and may take default_option. Each radio box is its own entry with group and option_label; entries with the same group form one question of 2 to 10 boxes for one signer on one document.

The reply is 201 with the envelope id and fields_required: false. Send it with POST /api/v1/envelopes/{id}/send. Without fields you get fields_required: true and an editor_url for placing them by hand.

Over the API, uploads must be PDFs of up to 25 MB and 50 pages, and an envelope takes up to 15 documents (50 through from-refs), 50 recipients and 500 fields. Envelopes created over the API also count against an API allowance of 100 a month on Pro and 500 on Team, with no cap on Enterprise. Envelopes you send from the dashboard never count against it.

Webhooks and MCP

To hear about changes without polling, subscribe to webhooks in Settings, Integrations, or over the API with POST /api/v1/webhooks. The Integrations article explains the signature, and the Webhooks page shows the payload.

The MCP server lets Claude Code, Claude Desktop and Cursor work with envelopes through the same API and the same token. It is a single file, server.mjs, run with Node, and it reads the token from VG_SIGN_API_TOKEN. Download it and check it against the published checksum rather than copying it by hand:

curl -fsSLO https://vg-sign.com/mcp/server.mjs
curl -fsSL https://vg-sign.com/mcp/server.mjs.sha256 | sha256sum -c -
{
  "mcpServers": {
    "vg-sign": {
      "command": "node",
      "args": ["/path/to/server.mjs"],
      "env": {
        "VG_SIGN_API_TOKEN": "vgs_live_…",
        "VG_SIGN_DOWNLOAD_DIR": "/path/to/a/downloads/folder"
      }
    }
  }
}

It can list and read envelopes and templates, create an envelope from a template, send, remind and void it, and download the signed PDF and the certificate. It cannot upload a new PDF; do that in the app or through the API. Sending, reminding, voiding and creating-with-send all act on real envelopes and email real people; voiding is what undoes a send, and a void itself cannot be undone by another call.

There are no per-scope tokens, so the assistant can do anything the token can. Mint it in a dedicated workspace if you want to limit what it can reach. Rotating the token (Settings, Integrations) replaces it at once and breaks every other integration using the old one, so rotate it whenever it may have been exposed.

To put signing inside your own product, the embed widget (in beta) mounts the signer in an iframe from one script tag and reports signed and declined events to your page over postMessage. Framing is denied until we add your site’s origin to the allowlist, so request access first; the Embed widget page has the details.

Back to help center

  • Slot VG·Sign into your stack.

    Post envelope events to a Slack or Microsoft Teams channel, or send signed JSON to any HTTPS address, including Zapier, Make and n8n. All of it is set up in Settings, under Integrations.

    Read
  • Build once, send forever.

    A template keeps an envelope’s documents, field layout and signing roles. Fill in names and emails to start a new envelope from it, or send one envelope for every row of a CSV file.

    Read
  • Plans, invoices and seats.

    Free covers 5 envelopes a month. Pro is one sender at a flat monthly price; Team is priced per person for 2 to 10 people.

    Read