Documentation
Documents

Send documents for signature

Documents holds the PDFs your org sends for signature, and every signature that comes back. A person signs one of three ways: from a link sent to an email address, at the visitor kiosk, or inside a playbook task. Each way keeps the same evidence: the exact wording agreed to, the file's SHA-256, and the time.

The app is on when Visits or Playbooks is on for you. Open it at /documents.

The Library

The Library at /documents/library is the list of templates. A template is one PDF, up to 25 MB. Managers and administrators upload and delete. Every member can view and send.

  • Upload: pick a PDF and give it a name. The server computes the file's SHA-256 on upload. This hash is what each signature names.
  • Replace file: uploads a new version. The template sends the new version from then on. Every earlier version stays, because a request or a signature can point at it.
  • Versions: lists each version with its number, its hash, and who signed it.
  • Fields: opens the placement editor under the row. Pick a kind (signature, initials, text, date, or checkbox), click the page to place a box, drag it to move it, and drag its corner to resize it. Click a box to change its label, its kind, or its required flag.
  • Seeded fields: a PDF that carries its own form gets one field per form widget, on its page, at its rectangle. Placed fields are never overwritten.

Send for signing

Click Send on a template. The dialog takes an email address, an optional name, optional CC addresses, an optional message, and how long the link lives: 48 hours, 7, 14, 30, or 90 days, or no expiry. The default is 48 hours.

  • The recipient gets one email with a link. The link opens the signing page. No account is needed.
  • A CC signs nothing. Up to 10 addresses, separated by commas. When the last signer has signed, each signer, each CC, and the sender get one email with the executed PDF attached and a link to its page. A PDF larger than 10 MB comes as the link alone, and the email says so.
  • The request copies the template's fields and version at send time. A later change to the template changes nothing for this recipient.
  • One reminder goes out by itself three days after the send, if the document still waits. Click Remind on the request to send one by hand at any time.
  • A template with no fields still signs: the signer types their name and agrees. Nothing is drawn on the page itself.

The signer's page

The link renders the PDF in the browser with each field drawn in place. The form under the document holds the inputs, so the page works the same at phone width.

  1. Complete the fields. Tap a signature or initials box to open the pad: draw with a finger or a mouse, or type.
  2. Type your full legal name. The typed name is the signature.
  3. Tick the agreement and click Sign.

After the signature the signing link shows who signed and when, and a button to the page of the document on OrgOrg. The receipt, the wording agreed to, the file hash, each value, and the signed copy are on that page, after a sign-in with the address the document was sent to. The signer also gets an email with the link.

The executed copy also has a page on OrgOrg, at /executed/<request id>. It opens after a sign-in: a member of the org opens it when the request is shared with them, and a signer or a copied address opens it with the address the document was sent to. Each time the page shows the document, OrgOrg keeps the time and the address of the viewer.

A signer who does not want to sign clicks Decline to sign and can give a reason. The link stops working, and the sender hears about it. An expired or cancelled link shows what happened and asks the signer to request a fresh one.

Sent for signing

/documents/requests lists every request the org sent, newest first, with its state and its timeline: sent, reminded, opened, and the outcome.

A request shows to the people it is shared with: at the send, the sender and each member of the org who is a signer or a copied address. The sender, or an admin the request is shared with, changes that with Share on the row, which also lists who opened the signed copy and when. The document, the receipt, and the signed copy follow the same list, also through the API.

  • Pending: the link works and waits for the signer. Actions: Open, Copy link, Remind, Cancel.
  • Signed: the receipt and the signed copy are available on the page of the signed document. Actions: Receipt, Signed copy, Share.
  • Declined: the signer refused. The row shows the reason when one was given.
  • Expired: the link reached its expiry with no signature. Send the template again to start over.
  • Cancelled: the sender cancelled the request. The link stays dead.

The signed copy is the source PDF with every value drawn in and a record page appended. When the copy could not be made, the row says so, and Retry signed copy makes it again. The signature record is complete without it.

The signed archive

/documents/signed answers what has been signed, by whom, and on which file.

  • Everyone (administrators only): every signature in the org, newest first, from all three sources. Filter by Sent by email, Playbooks, or Kiosk. Each row has the receipt and the signed copy.
  • By person: what one employee signed inside playbooks. An administrator picks anyone. Everyone else sees their own list.

Visitors at the kiosk

In Visits settings, the Visitor documents section picks templates from the Library. Each one is Agree or Sign. The kiosk renders the PDF at check-in, and the visitor accepts each document, or types their full name for a Sign document. Each acceptance records the template, the exact version, its hash, the wording, and the time, and gets a signed copy with a record page. Removing a template from the Library takes it off the kiosk.

Employees in a playbook

A playbook template item can carry a document. When the playbook runs, the task shows the document, and the person reads it, types their name, and agrees. Nobody signs on behalf of someone else. The task completes with the signature in one step, and the signature appears at /documents under To sign until it is done.

Notifications

The person who sent a request hears when it is signed, declined, or expired, in the inbox and, by their preferences, by email and in Slack. The Documents category is at /user/settings/notifications.

API and CLI

The public API has four endpoints under /api/v1/documents, with the scopes documents:read and documents:write. The full reference is at /docs/api/v1/documents.

  • GET /templates/list: the templates.
  • GET /requests/list: the requests, with status and since filters.
  • GET /requests/get: one request with its receipt and a short-lived URL for the file that was signed.
  • POST /requests/send: send a template to an address, with an optional expiresInDays and an optional cc list of addresses that get the signed copy.

The orgorg CLI wraps the same endpoints:

orgorg documents templates-list
orgorg documents requests-list --status Signed --since <ms>
orgorg documents requests-get --id <requestId>
orgorg documents requests-send --templateId <id> --email who@example.com

The file URL in a request expires soon after it is minted. An importer downloads it at once.

Related

API tokens explains how to mint a token with the documents scopes, and Download lists every OrgOrg app.