Skip to content
Docs
Documents & e-signature

Documenso

Let hires send documents from your Documenso templates for signature, after a person approves, follow who has signed, and be woken when a document is signed.

Explore 6 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Documenso, the open-source e-signature platform, connected (on Documenso's cloud or your own server), a hire can:

  • list your templates and the roles each one needs filled (like Client),
  • prepare a document from a template as a draft, for someone to check and send,
  • send a document from a template for signature, always after a person approves,
  • see a document's status and each signer's: waiting, viewed, signed or declined,
  • get a signed copy's reference: its file name, size and fingerprint, and where to download it.

Sending always asks first

Sending a document for signature commits your business, so send_for_signature always waits for an approval. The hire asks in the thread with the template, the title, every signer and the message; when the approver says yes, Roster sends exactly that, once. Drafts reach nobody and don't ask.

1. Make an API token in Documenso

API tokens belong to a team: in Documenso, open the team hires should use, then Team settings → API tokens (the address ends in /t/<team>/settings/tokens).

  1. In Documenso, open Settings → API tokens (in the team whose templates hires should use).
  2. Create a token named Roster and copy it.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Documenso and choose it.
  2. API token: paste the token.
  3. Documenso address: leave https://app.documenso.com, or put your own Documenso's address.
  4. Business name: your business's name, like Bayt Studio. Signing emails are sent in this name.
  5. Documents hires may see: Only documents made through Roster (the default), or Every document this account can see. An e-signature account often holds contracts, offers and HR papers, so by default hires only see what they drafted or sent themselves.
  6. Click Connect.

Roster checks the key when you click Connect. Once it's accepted, the connection shows Connected as Documenso and the address it's at. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Documenso:

  • Read only: it can list templates, see documents' status and get signed copies' references.
  • Read and write: it can also draft documents and send them for signature (sending always asks a person first).
  • Templates: template names or IDs it may use. Leave it empty for every template.
  • Who it may send to: email domains (like client.example) or full addresses. Anyone else is refused, even with an approval.

Hires never get the signed PDF itself: they get its name, size and SHA-256 fingerprint, and the link where people signed in to Documenso download it.

4. Get told when documents are signed (optional)

Without this, a hire watching Documenso checks for finished documents now and then. To hear at once:

  1. Copy this connection's webhook address from its card in Roster.
  2. In Documenso, open Settings → Webhooks and create a webhook with that address. Choose at least Document signed, Document completed and Document rejected, and give it a secret.
  3. Paste the same secret in Webhook secret on the connection.

Roster ignores any delivery that doesn't carry that secret.

Saying it's an AI assistant

A hire never pretends to be a person. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then the message in the first signing email to someone starts with "This is the AI assistant for" and your business name.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Documenso and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Documenso: Settings → API tokens → Create token. Templates and documents are the token's team's.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Documenso connection fields
FieldWhat to provide
API token
token
Required · sealed secret		In Documenso: Settings → API tokens → Create token. Templates and documents are the token's team's.
Documenso address
url
Optional		https://app.documenso.com, or your own Documenso's address.

Starts with: https://app.documenso.com.

Business name
businessName
Required		Signing emails are sent in this name. Never a made-up person's name.
Documents hires may see
visibility
Optional		E-signature accounts hold contracts, offers and HR papers. By default hires see only what they drafted or sent through Roster.

Choices: Only documents made through Roster (roster); Every document this account can see (all).

Starts with: roster.

Webhook secret
webhookSecret
Optional · sealed secret		Optional: the secret of a webhook (Settings → Webhooks) sent to this connection's address. Signatures then wake hires at once.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Documenso per-hire limits
FieldWhat to provide
Templates
templates
Optional		Template names or IDs it may use. Leave empty for every template.
Who it may send to
signers
Optional		Email domains or full addresses it may send documents to. Leave empty for anyone (sending always asks a person first).

Actions

6 actions: 4 only read and 2 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

6 of 6 actions. Open an action for its arguments and full input schema.

list_templatesRead only

Documenso templates this hire may send, with the roles each one needs filled.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_documentsRead only

Documents in Documenso, newest first: their status and how many have signed. By status (draft, sent, completed, declined, voided, expired) or words in the title.

Approval: Uses your workspace and hire approval settings.

Arguments for list_documents
ArgumentTypeDetails
statusOptional"draft" | "sent" | "completed" | "declined" | "voided" | "expired"See input schema below.
wordsOptionalstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "completed",
        "declined",
        "voided",
        "expired"
      ]
    },
    "words": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
get_statusRead only

A document's status in Documenso, with each signer's: waiting, viewed, signed or declined (and why).

Approval: Uses your workspace and hire approval settings.

Arguments for get_status
ArgumentTypeDetails
documentRequiredstringthe document's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "document": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the document's ID"
    }
  },
  "required": [
    "document"
  ]
}
signed_copyRead only

The signed PDF of a completed Documenso document, as a reference: its name, size and SHA-256 fingerprint, and where people download it. Hires never get the file itself.

Approval: Uses your workspace and hire approval settings.

Arguments for signed_copy
ArgumentTypeDetails
documentRequiredstringthe document's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "document": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the document's ID"
    }
  },
  "required": [
    "document"
  ]
}
create_draftRead and write

Prepare a document from a template as a draft in Documenso, for a person to check and send. Nobody receives anything.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft
ArgumentTypeDetails
templateRequiredstringthe template's name or ID, from list_templates
titleRequiredstringthe document's title, as signers will see it
signersRequiredobject[]See input schema below.
subjectOptionalstringthe signing email's subject
messageOptionalstringthe signing email's message, plain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the template's name or ID, from list_templates"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the document's title, as signers will see it"
    },
    "signers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "the template's role this person fills, as list_templates shows"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          }
        },
        "required": [
          "role",
          "name",
          "email"
        ]
      }
    },
    "subject": {
      "description": "the signing email's subject",
      "type": "string",
      "maxLength": 200
    },
    "message": {
      "description": "the signing email's message, plain text",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "template",
    "title",
    "signers"
  ]
}
send_for_signatureRead and write

Make a document from a template and send it for signature: every signer gets Documenso's email with your subject and message. It's a commitment in your business's name, so it waits for a person's approval: Roster asks in the thread with everything below, and sends exactly that, once, when they approve. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: Always asks for approval.

Arguments for send_for_signature
ArgumentTypeDetails
templateRequiredstringthe template's name or ID, from list_templates
titleRequiredstringthe document's title, as signers will see it
signersRequiredobject[]See input schema below.
subjectOptionalstringthe signing email's subject
messageOptionalstringthe signing email's message, plain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the template's name or ID, from list_templates"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the document's title, as signers will see it"
    },
    "signers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "the template's role this person fills, as list_templates shows"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          }
        },
        "required": [
          "role",
          "name",
          "email"
        ]
      }
    },
    "subject": {
      "description": "the signing email's subject",
      "type": "string",
      "maxLength": 200
    },
    "message": {
      "description": "the signing email's message, plain text",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "template",
    "title",
    "signers"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • Incoming webhooks are supported. Use the callback address shown on the connection and follow the setup guide.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Miro

Boards, sticky notes, diagrams and frames.

DocuSign

Let hires send envelopes from your DocuSign templates for signature, after a person approves, follow who has signed, and be woken when an envelope is signed.

On this page

1. Make an API token in Documenso2. Connect it in Roster3. Give hires access4. Get told when documents are signed (optional)Saying it's an AI assistantTools and permissions reference