API Authentication

Use this guide for authentication, team-scoped URLs, and the most common API flows. For endpoint-by-endpoint request bodies, response schemas, and live examples, use the API Reference.

Create an API token

Go to Settings > Developer
Enter a descriptive token name such as Production API or CI
Click Create Token
Copy the token immediately

Important: Tokens are only shown once. Store them securely and never commit them to source control.

Papyrus currently allows up to 25 active API tokens per user.

Understand the base URL

Every API request uses both:

A Bearer token in the Authorization header
Your team slug in the URL path

If your dashboard URL is https://your-app.test/acme-corp/dashboard, your team slug is acme-corp and your API base URL is:

https://your-app.test/api/v1/acme-corp/

If a user belongs to multiple teams, change the slug to work inside a different team context.

Make your first request

This example lists sent documents, includes recipients, and sorts newest first:

curl -G "https://your-app.test/api/v1/acme-corp/documents" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "filter[status]=sent" \
  --data-urlencode "include=recipients" \
  --data-urlencode "sort=-createdAt"

Papyrus uses a consistent query style for read endpoints:

filter[...] for filters such as filter[status]
include for related data such as include=recipients
sort for sorting such as sort=-createdAt
page and perPage for pagination

Use the API Reference to see the exact filters, includes, and sorts supported by each endpoint.

Common integration flow

Most integrations follow the same path:

Look up the template you want to use
Inspect its roles and preFillKey values
Create a document from that template
Decide whether Papyrus emails signers or your app embeds signing
Track progress with webhooks, if available for your team, and follow-up API calls

1. Inspect the template first

Templates define the roles and fields your request must satisfy. A common first step is fetching the template with its fields so you know:

Which roleLabel values to send for each signer
Which preFillKey values can be used in preFillValues
Whether the template is a good fit for email sending, embedded signing, or a direct link flow

If you plan to manage direct links over the API, make sure embedded signing features are enabled for your team first.

See the API Reference for the templates endpoints, and the Templates guide for the workflow behind them.

2. Create a document from a template

POST /api/v1/{team}/templates/{template}/documents is the main automation entry point. A typical request looks like this:

curl -X POST "https://your-app.test/api/v1/acme-corp/templates/12/documents" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Thompson Plea Agreement",
    "signingOrder": "sequential",
    "recipients": [
      {
        "roleLabel": "Attorney",
        "name": "Peter Hibbard",
        "email": "peter@example.com"
      },
      {
        "roleLabel": "Prosecutor",
        "name": "Grant County Prosecutor",
        "email": "prosecutor@example.com"
      }
    ],
    "preFillValues": {
      "defendant_name": "James Robert Thompson",
      "charge_number": "T00087521",
      "charge": "46.16A.030 - Expired Vehicle Registration"
    },
    "externalId": "order-456",
    "sendEmails": true
  }'

Keep these rules in mind:

roleLabel must match a role defined on the template
preFillValues keys must match the template field's preFillKey
signingOrder accepts parallel or sequential; if omitted, Papyrus uses parallel
externalId is useful for mapping Papyrus documents back to your system
sendEmails controls whether Papyrus sends the invitations immediately
expiresInDays is optional and supports values from 1 to 365
For standard email signing, you can omit recipient auth fields entirely
Only send recipient auth fields when you need access_code or sms verification

In sequential flows, only the active signer gets a live signing link at first. Later signers stay pending until their turn, so their signingUrl and embedUrl remain null until Papyrus advances the workflow.

3. Choose email delivery or embedded signing

After document creation, you usually branch into one of two flows.

Send email invitations

Keep sendEmails set to true
Papyrus emails signer recipients for you
In sequential mode, only the first signer is emailed immediately
Use Webhooks to react to sent, signed, and completed events if webhooks are enabled for your team

Embed signing in your app

Set sendEmails to false
Use the signingUrl or embedUrl returned in the 201 Created response
If you need them again later, fetch the document with include=recipients

For full iframe guidance, event handling, and security recommendations, see Embed Integration.

4. Operate on sent documents

Once a document is in progress, the most common follow-up actions are:

Resend an invitation to a signer
Update mutable metadata such as emailSubject, emailMessage, or externalId
Void a sent document
Download the finalized PDF
Fetch the document again with include=recipients

Those actions are all covered in the API Reference. The Sending for Signature guide explains the business flow behind them.

Signer authentication

When you create a document from a template, you can require additional signer verification per recipient:

none for no extra challenge
access_code for a passphrase
sms for a one-time code sent to a phone number in E.164 format

For the most common email-only flow, omit authMethod, accessCode, and authPhone completely.

Use signer authentication when you need more confidence that the recipient is the intended signer. Share access codes out-of-band, and keep phone numbers in international format such as +15551234567.

Working with responses

Papyrus uses standard JSON error responses. The most common status codes are:

401 when the token is missing or invalid
403 when the token owner cannot access that team or resource
404 when the resource does not exist in the current team context
422 when request validation fails
429 when you hit the rate limit

For full request and response schemas, use the API Reference.

Revoke a token

To revoke a token:

Go to Settings > Developer
Find the token in the list
Click Delete

The token is invalid immediately.

Security checklist

Create separate tokens for local, staging, and production systems
Store tokens in environment variables or a secrets manager
Rotate tokens when ownership or deployment scope changes
Always send requests over HTTPS
Use externalId and Webhooks so your backend can reconcile state
Treat returned signingUrl, embedUrl, and direct-link URLs as sensitive

Where to go next

API Reference - exact endpoints, schemas, and query parameters
Templates - how roles and pre-fill keys are modeled
Embed Integration - embedding signer flows in your app
Webhooks - reacting to document lifecycle events