Quickstart

This guide walks you through provisioning an API key, uploading a document, and sending an envelope.

All cURL examples below target https://app.legesis.com. The host is sourced from NEXT_PUBLIC_DOCS_API_BASE at build time; it falls back to https://app.legesis.com for the public docs site.

1. Get an API key

Sign in to the legesis dashboard and visit Settings → API tokens. Create a token with at least the envelopes:write, files:write, and events:read scopes. SmartTag analysis additionally requires files:read and the smartTags workspace feature.

API keys are workspace-scoped. They identify both the workspace and the permissions of the caller. Treat them like passwords — never commit them.

2. Upload a document

curl -X POST $LEGESIS_API_BASE/api/v1/files \
  -H "X-API-Key: $LEGESIS_API_KEY" \
  -F "file=@contract.docx"

The response includes a file_id and metadata such as page count and MIME type.

3. (Optional) Run SmartTag analysis

If your document contains SmartTag placeholders like {{signature|buyer|required:true}}, ask legesis to extract them:

curl -X POST $LEGESIS_API_BASE/api/v1/files/$FILE_ID/smart_tag_analysis \
  -H "X-API-Key: $LEGESIS_API_KEY"

The response lists every detected field with its type, signer alias, and position. You can pass this list straight into envelope creation.

4. Create an envelope

POST /envelopes requires an Idempotency-Key header — the server returns a 400 Bad Request without one.

curl -X POST $LEGESIS_API_BASE/api/v1/envelopes \
  -H "X-API-Key: $LEGESIS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Master Services Agreement",
    "files": [{ "file_id": "'$FILE_ID'" }],
    "recipients": [
      { "alias": "buyer", "email": "alex@example.com", "name": "Alex Doe" }
    ]
  }'

The envelope is created in draft status.

5. Send the envelope

POST /envelopes/:id/send also requires an Idempotency-Key header.

curl -X POST $LEGESIS_API_BASE/api/v1/envelopes/$ENVELOPE_ID/send \
  -H "X-API-Key: $LEGESIS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Recipients receive an email with a unique signing link. The envelope transitions to sent and webhook events start firing.

Next steps

• Authentication — scopes, rotation, idempotency.
• Envelope lifecycle — every state transition explained.
• API reference — every endpoint with a live playground (Try-It panel coming in week 3).