Breadcrumbs

Documents & Files

Signing is what Circularo is for, but a document exists before anyone signs it. This chapter covers that life: getting content in, describing it, finding it again, adding to it, organizing it, and taking the results back out.

Files and documents

The two are deliberately separate:

  • A file is raw content — the bytes of a PDF, an image, a finished archive. It is uploaded on its own, identified by an opaque id, and takes on a role only once something references it.

  • A document is what Circularo manages: one main file plus a title, structured data, attachments, a place in your folders, an evidence trail, and exactly one transaction.

That split is why the same file endpoint serves everything binary: the PDF you upload, the signed result, an image embedded into a page, an export archive. Whenever an endpoint hands you a fileId, the content behind it is one download away.

Around the main file, a document carries:

  • Metadata fields — the structured values of the metadata definition it was created with, which is also what you can search on.

  • Custom fields — your own key/value data, for identifiers that belong to your system rather than to Circularo.

  • Attachments and submitted files — supporting content alongside the main file, the second kind contributed by recipients.

  • Annotations, images and signatures — everything applied onto the pages, whether by you or by a recipient.

  • Placements — where the document sits in the folder trees, one entry per tree.

How the pieces come together

A typical integration works in this order:

  1. Get the content in — upload a file, or hand its content to the call that creates the document.

  2. Create the document and describe it, so people and searches can find it later.

  3. Do something with it — send it for signature (Signing & Approvals), or add your own content and seal it.

  4. Find it again by its attributes rather than by an identifier you stored.

  5. Collect the outcome — the signed file, the audit trail, the certificate, or a whole archive of them.

Worth knowing across the chapter

  • Identifiers are opaque. Keep the ones you are given; never build one or read meaning into its shape.

  • Deleting is reversible by default. A document goes to the trash and can be restored; removing it for good is an explicit request.

  • A read always returns the same representation. Creating, retrieving, annotating and cloning all answer with the same document object, so one parser covers them all.

  • Documents carry a version. Reads return it as an ETag, and writes can be guarded with If-Match — see Guard concurrent writes.

Where to start

Begin with Upload and download files and Create a document from a file: together they cover the path from bytes on your disk to a document Circularo manages. Store structured data on a document then makes that document describable, and searchable.

From there, pick by task: