Quickstart

Send a PDF for signature, follow it, and download the result. Everything below is described field by field in the API reference.

The base URL is https://europe-west2-mostly-sign.cloudfunctions.net/apiV1Envelopes. Paths in this guide are relative to it.

# 1. Get an API key

Mint a key in the MostlySign dashboard. API keys require a paid plan and carry the pdf:run scope. Keys start with sk_ and are stored only as a SHA-256 hash, so a lost key must be rotated, not recovered.

Send it on every request, as either header:

Authorization: Bearer sk_...
X-API-Key: sk_...

A Mostly Tiny identity token (mtid1_...) is also accepted. A missing or invalid key returns 401.

# 2. Create an envelope

POST / with a base64 PDF, who signs, and where each field goes.

curl -X POST "$BASE/" \
  -H "Authorization: Bearer $MOSTLYSIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mutual NDA",
    "recipients": [{ "email": "bob@example.com", "name": "Bob Signer" }],
    "placements": [
      { "kind": "signature", "page": 1, "recipient": 0, "x": 0.1, "y": 0.8, "w": 0.4, "h": 0.06 }
    ],
    "pdfBase64": "'"$(base64 < nda.pdf | tr -d '\n')"'"
  }'

Things to know:

• Placement coordinates are fractions of the page (0 to 1), origin bottom-left. recipient is an index into recipients.
• Every recipient needs at least one signature placement.
• Limits: PDF up to 10 MB, 1 to 5 recipients, 1 to 40 placements. How many signers a document may have is also a plan limit; the Free plan allows one.
• routing is parallel (default, everyone is emailed at once) or sequential (one at a time, in array order).
• expiresInDays defaults to 30 (maximum 90).
• A recipient can be gated with an accessCode that you deliver out of band. MostlySign stores only its hash and never emails it.

The 201 response:

{
  "id": "env_9f3a7c21b4e05d8a",
  "status": "sent",
  "recipients": [{ "email": "bob@example.com", "signingUrl": "https://..." }]
}

The signingUrl values are returned once and cannot be retrieved later. Keep them if you want to embed signing in your own UI instead of relying on the emails.

# 3. Check progress

GET /{envelopeId} returns the status, per-recipient status and the audit trail. GET / lists your 50 most recent envelopes.

Envelope status is one of sent, viewed, completed, declined, voided, expired. Rather than polling, set a webhookUrl when you create the envelope: see Webhooks.

# 4. Download the result

GET /{envelopeId}/download returns { "url": "...", "final": true }. The URL is valid for 15 minutes. final is true once the envelope is completed; before that you get the working copy with the signatures so far and final is false.

# 5. Cancel an envelope

POST /{envelopeId}/void invalidates every outstanding signing link. A completed envelope cannot be voided and returns 409.

# Errors

Error bodies are { "error": "...", "code": "..." }. 400 is a malformed request, 401 a bad key, 403 a missing scope or a plan that does not allow the request, 404 an unknown envelope, 429 rate limiting or an exhausted plan allowance.