Skip to content

Reference

Cheat sheet

Every common SignatureAPI operation as a CLI command and as a curl request, side by side, for envelopes, recipients, events, deliverables, and uploads.

Each operation below shows the CLI command and the matching REST API request with curl. Both send the same request.

The curl requests read the key from SIGNATUREAPI_KEY, the variable init writes. Export it from your env file first, for example with set -a; . ./.env; set +a. The CLI acts in test mode unless you pass --mode live or use a live key; curl acts in the mode of the key you send.

envelope.json is a Create an envelope body, such as the one in Request bodies.

Envelopes

Create and send an envelope

CLI
npx signatureapi envelopes create --body envelope.json
curl
curl -X POST https://api.signatureapi.com/v1/envelopes \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/json" \
  -d @envelope.json

List envelopes

CLI
npx signatureapi envelopes list --status completed --limit 20
curl
curl "https://api.signatureapi.com/v1/envelopes?status=completed&limit=20" \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

For the next page, pass the result’s next_cursor to the CLI as --cursor, or follow links.next with curl.

Get an envelope

CLI
npx signatureapi envelopes get eb4cf433-a8af-4161-b37b-7ef57d423e56
curl
curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56 \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

Cancel an envelope

The CLI asks for confirmation before it cancels or deletes. In a script, add --yes.

CLI
npx signatureapi envelopes cancel eb4cf433-a8af-4161-b37b-7ef57d423e56 --reason "Replaced by a new version"
curl
curl -X POST https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/cancel \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Replaced by a new version"}'

Delete an envelope

Only a completed, canceled, or failed envelope can be deleted.

CLI
npx signatureapi envelopes delete eb4cf433-a8af-4161-b37b-7ef57d423e56
curl
curl -X DELETE https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56 \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

Recipients

Resend a signing request

CLI
npx signatureapi recipients resend re_49r1R2jpPDz8hSpP75ZkPp
curl
curl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/resend \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

Replace a recipient

CLI
npx signatureapi recipients replace re_49r1R2jpPDz8hSpP75ZkPp --name "John Smith" --email john.smith@example.com
curl
curl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/replace \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Smith", "email": "john.smith@example.com"}'

Create a ceremony

ceremony.json is a Create a ceremony body, such as {"authentication": [{"type": "email_link"}]}.

CLI
npx signatureapi recipients ceremony re_49r1R2jpPDz8hSpP75ZkPp --body ceremony.json
curl
curl -X POST https://api.signatureapi.com/v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/json" \
  -d @ceremony.json

Events and deliverables

List an envelope’s events

CLI
npx signatureapi events list --envelope eb4cf433-a8af-4161-b37b-7ef57d423e56
curl
curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/events \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

List an envelope’s deliverables

CLI
npx signatureapi deliverables list --envelope eb4cf433-a8af-4161-b37b-7ef57d423e56
curl
curl https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56/deliverables \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

Get a deliverable

CLI
npx signatureapi deliverables get del_6FF89lKNyTNamOJCJd1tLL
curl
curl https://api.signatureapi.com/v1/deliverables/del_6FF89lKNyTNamOJCJd1tLL \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

Uploads

Upload a document

CLI
npx signatureapi uploads create contract.pdf
curl
curl -X POST https://api.signatureapi.com/v1/uploads \
  -H "X-API-Key: $SIGNATUREAPI_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @contract.pdf

Use the returned url as a document’s url in envelope.json. Uploads expire after 24 hours.

Inspect an upload

CLI
npx signatureapi uploads inspect upl_3JJz6t1o8A5YjX5VpnX27Z
curl
curl https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z/structure \
  -H "X-API-Key: $SIGNATUREAPI_KEY"

CLI only

These commands have no curl equivalent: they set up your machine rather than call one API operation.

TaskCommand
Write the test API key into .envnpx signatureapi init
Write a new live key into another filenpx signatureapi init --mode live --env-path .env.live
List API keysnpx signatureapi api-keys list
Roll the test keynpx signatureapi api-keys roll key_... --mode test --replace
Receive test webhooks at a local handlernpx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks
Send an example event to the listenernpx signatureapi trigger envelope.completed
Show the account the CLI acts fornpx signatureapi whoami
Set up a coding agentnpx signatureapi agent setup --skills --mcp --agent claude-code --yes

Add --json to any command for machine-readable output. The full option list for each command is in Resources and in npx signatureapi <command> --help.