Signing & Approvals

Signing is the core of Circularo: you take a document, ask people to act on it, and end up with a legally binding result and a full evidence trail. This chapter covers every way to run that process: a single signer or routed rounds of several people, fields placed where they belong, links you hand out yourself, identity checks, prepared templates, and signing a document alone.

The transaction model

A transaction is the process of getting one document acted on — the noun you will work with the most:

• A transaction runs on exactly one document, and a document runs exactly one transaction. Start from a document you already have, from a file, from content sent inline with the transaction, or from a template a colleague prepared.

• A transaction usually has recipients: people asked to act on the document. Each is asked to do one thing — their purpose. Common purposes are sign, approve and view; the API reference lists the full set. At least one recipient must be asked to act, so a transaction cannot consist of view recipients only.

• Every recipient is required by default; set isMandatory to false for one whose action is welcome but not needed, and the transaction can finish without them.

• Permissions decide what a recipient may do with the document besides acting on it — printing it, attaching files, or handing their action to somebody else, which is the one thing they do not get by default. Granting that one, delegate, needs the share_delegate right on your own account, whether you grant it when sending or add it later.

• A transaction can also carry what you apply yourself — your own signature, added the moment it is created. A transaction that only does that is finished as soon as it starts — there is nobody to wait for, and its responses show you as a single, already completed recipient.

• A transaction places fields on the document for recipients to fill: signature fields, form fields and image fields.

• A transaction carries a status that advances as recipients act, and each recipient carries their own status alongside it.

Delivery and routing

Recipients act in one of two ways, and you choose per transaction:

• In parallel (the default): everyone is asked to act at once.

• Sequentially: recipients act one round after another, in their order. Recipients sharing an order act together in the same round, and a quorum on that round lets a subset of them settle it — any two of three approvers, for instance.

By default Circularo e-mails each recipient an invitation with a link to the document. When your own application should deliver it instead — a portal, a checkout flow, your own message — you ask for the recipient's link and pass it on yourself.

Statuses

A transaction moves from not-started to in-progress and then to one terminal status: completed, rejected, cancelled or expired. Recipients have their own live statuses while the transaction runs — queued, pending, viewed — and settle into completed, rejected, superseded, cancelled or expired — though not every recipient settles: once a transaction ends, recipients that never acted keep the status they had. The transaction's own status is what says whether anything more will happen.

Rejection is the outcome one recipient decides for everybody. The moment somebody refuses, the transaction ends as rejected, later rounds are never asked, and the recipients who never got their turn stay queued. That recipient's own status is rejected, and the reason they gave is kept in the document's history. An integration that only watches for completed therefore waits forever — branch on the terminal status, not on the one you hoped for.

Before you begin

• Recipients do not need a Circularo account. A plain e-mail address is enough; they act through the link Circularo sends them — as long as your own account may share outside the organization, which GET /me reports as settings.canShareWithExternalUsers.

• Some options need more than the permission to call the endpoint. Requiring identity verification, applying your own signature or granting delegation each depend on a further right that the endpoint itself does not ask for; the page that uses one says so up front.

Where to start

If you have not run the Quickstart: send your first document for signature yet, do that first — it sends a document to one signer in three calls, and every page here builds on it.

From there each page adds one thing:

• Route a document through several people — Send a document to several recipients in order.

• Control where every field lands — Place fields on the document, or Position fields with anchor text to tie them to the wording instead of to coordinates.

• Deliver the document yourself, and decide how recipients prove who they are — Hand out signing links yourself and Verify recipient identity.

• Keep a running transaction moving — Manage a running transaction.

• Send what colleagues have prepared, or sign alone — Send a document from a template and Sign a document yourself.

Run a complete agreement end to end then puts all of it together in one realistic agreement. Taking any of this to production is the Robust Integrations chapter: errors, retries, and tracking changes with webhooks.