Breadcrumbs

Getting Started

The Circularo API lets you build document signing and management into your own product. You upload files, create documents, send them to recipients for signature or approval, and collect the evidence — all server-to-server, authenticated with a single API key.

Core concepts

Five nouns cover most of what you will touch:

  • A file is raw binary content — a PDF you upload, a signed PDF you download. Files are referenced everywhere else by their id.

  • A document is the unit Circularo manages: a main file plus a title, metadata, placement in folders, and a full evidence trail.

  • A transaction is the signing or approval process of one document: who has to act, in what order, and what the outcome was. A document runs one transaction.

  • A recipient is a party asked to act in a transaction — for example sign, approve or accept. A plain e-mail address is enough; recipients do not need a Circularo account, provided your own account may share outside the organization.

  • A metadata definition describes the structured fields a document can carry — think of it as the document's form template.

Everything you create lives in your organization and is visible to the API according to the same permissions your users have in the Circularo application.

How a typical integration works

Most integrations follow the same shape, whatever they automate:

  1. Provide the document. Upload the file with POST /files and reference its id, or hand the content to the transaction call directly — the quickstart does the latter, which keeps the whole flow to three endpoints.

  2. Send it for signature with POST /transactions: the recipients, the order they act in, and the fields they fill.

  3. Recipients act in Circularo. By default they receive an e-mail invitation, open the document and sign, approve or reject it; your system is not involved in this part unless you choose to deliver the link yourself.

  4. Track the transaction with GET /transactions/{id}, by polling or with webhooks.

  5. Collect the result — download the signed PDF and, when needed, the audit trail that documents who did what and when.

The chapters after this one go deep on each part. Signing & Approvals covers every variant of sending — several recipients, placed fields, your own signing links, identity verification, templates, and signing a document yourself. Documents & Files covers content, search, folders, and evidence. Robust Integrations covers errors, retries, paging, and concurrency. Administration covers users, groups and audit logs, and Reporting covers the state of the work across the organization.

Requests and responses

  • All paths in these tutorials are relative to your instance's base URL; the examples use https://sandbox.circularo.com/api/v1/public. Each environment — production, or a testing instance — has its own base URL and its own API keys.

  • Every request authenticates with an API key in the Authorization: Bearer YOUR_API_KEY header.

  • Request and response bodies are JSON (Content-Type: application/json), except file uploads (multipart/form-data) and binary downloads.

  • Identifiers are opaque strings: keep the ones you are given, and never build them yourself or read meaning into their shape.

  • Every failed request returns one uniform error envelope with a machine-readable type and a requestId for support.

The API reference documents every endpoint, parameter, and error code; these tutorials teach the tasks and point at the API reference where details matter.

Where to start

Read Authenticate and manage API keys to get a key and make your first authenticated call. Then follow Quickstart: send your first document for signature — the whole path from a PDF to a signed file, over three endpoints.

Once that works, Signing & Approvals takes the sending part as far as it goes, and Robust Integrations covers the mechanics every production integration needs: error handling, retries with idempotency, pagination, and concurrency.