# Documents and signing > Agreements, e-signatures and kept records such as tax returns. MCP toolset: `documents` (https://app.getoatmilk.com/api/mcp?toolset=documents) ## company - [`company.applyRecord`](https://app.getoatmilk.com/docs/api/company.applyRecord.md) — Save chosen facts of a kept company record into the company profile, replacing what is there, with documentId, fields (legalName, operatingName, businessNumber, corporationNumber, incorporationDate, jurisdiction, registration, gstHstAccount, gstHstEffectiveDate, gstHstFrequency, fiscalYearEnd, registeredOffice, directors, officers, shareholders), the profile's expectedRevision and idempotencyKey. Each saved fact notes the record as its source. - [`company.recordChanges`](https://app.getoatmilk.com/docs/api/company.recordChanges.md) — Read what a kept company record (documentId of a company_document: articles, a certificate, an Ownr or registry package, an annual return) says about the company compared with the company profile: describesCompany (true when its name or corporation or business number matches, null when the profile has none yet) and changes, each { key, label, current, value, kind }: fill for an empty profile field, conflict for a different value. Oatmilk never saves them on its own: an admin chooses which to use (company.applyRecord, or company.facts.review and company.facts.apply for every record at once). ## company.facts - [`company.facts.apply`](https://app.getoatmilk.com/docs/api/company.facts.apply.md) — Save the details a person chose from company.facts.review into the company profile, in one change: picks ([{ documentId, key }], one record per detail, from the options shown), checked (the ids of the records whose findings the person saw, so the ones they left aren't asked about again), expectedRevision (the review's revision) and idempotencyKey. Only call it after the person confirmed the values. Each saved detail notes its record as the source. A GST/HST number, registration date or filing frequency also marks the company as registered for GST/HST; a GST/HST number has to start with the business number. A changed profile is refused with CONFLICT: read the review again. Returns the saved profile and revision, applied and checked. Run accounting_compliance_refresh afterwards to rebuild the tax deadlines from the new details. - [`company.facts.review`](https://app.getoatmilk.com/docs/api/company.facts.review.md) — Read what the company's own records say about the company, for a person to check before anything is saved. Oatmilk reads every company record (articles, certificates, registry and annual returns, CRA business number and GST/HST registration letters) and every CRA tax record that prints a GST/HST (RT) account, and never saves what it found on its own. Input: optional documentIds to look at only those records (for example the files just uploaded); otherwise the newest 50 company and tax records. Returns revision (the company profile's, for company.facts.apply), documents (each record's id, title, filename, kind, createdAt, status: reading, to_check, nothing_new, other_company, unreadable or failed, and details, how many it has to check) and fields: one per profile detail with slot, key (legalName, operatingName, businessNumber, corporationNumber, incorporationDate, jurisdiction, entityCountry, formationJurisdiction, legalForm, usFederalTaxClassification, registration, gstHstAccount, gstHstEffectiveDate, gstHstFrequency, fiscalYearEnd, registeredOffice, directors, officers or shareholders), label, current (what the profile has now, or null), kind (fill when the profile is empty, conflict when it differs) and options (each value with the records that say it; two options mean the records disagree). pending is how many details wait to be checked. A finding a person already checked and left isn't listed again until the record says something new. Show the fields to the person and let them choose before calling company.facts.apply. ## documents.assets - [`documents.assets.confirm`](https://app.getoatmilk.com/docs/api/documents.assets.confirm.md) — Finish an image upload: checks the uploaded bytes against the declared type and SHA-256 and that the image can be printed, records its size, and returns it with a private link that shows it for about an hour. - [`documents.assets.list`](https://app.getoatmilk.com/docs/api/documents.assets.list.md) — List the images kept in the agreement library (logos, diagrams, stamps) with their titles, sizes and private links that show them for about an hour. Pass ids to get links for specific images, such as the ones a template places with asset:. - [`documents.assets.prepare`](https://app.getoatmilk.com/docs/api/documents.assets.prepare.md) — Start uploading an image for agreements, such as a logo, a diagram or a signature stamp: PNG or JPEG up to 10 MB and 6,000 pixels on a side, with its SHA-256. Pass saved: true to keep it in the library to reuse. Returns the image and, unless the organization already has this exact image, a private upload link: PUT the bytes there with their content type, then call documents.assets.confirm. Place a confirmed image in a template with a line ![Alt text](asset:?width=50&align=center); width is 10–100 percent of the text width (default 100) and align is left, center or right (default center). - [`documents.assets.update`](https://app.getoatmilk.com/docs/api/documents.assets.update.md) — Rename an image, keep it in or take it out of the library (saved), or archive it, with id, expectedRevision and idempotencyKey. Archived images still print where they are already placed. ## documents.comments - [`documents.comments.create`](https://app.getoatmilk.com/docs/api/documents.comments.create.md) — Add an auditable comment thread to an agreement template. A text selection may be anchored; mention IDs must belong to active members of this organization. Requires an idempotency key. - [`documents.comments.list`](https://app.getoatmilk.com/docs/api/documents.comments.list.md) — Read comment threads and replies for an agreement template in this organization, including resolved threads and their anchored text. - [`documents.comments.members`](https://app.getoatmilk.com/docs/api/documents.comments.members.md) — List active finance and administrator members in this organization who can be tagged in document comments. - [`documents.comments.reply`](https://app.getoatmilk.com/docs/api/documents.comments.reply.md) — Add an auditable reply to an open agreement-template comment thread. Participants and newly mentioned active organization members receive in-app notifications. Requires an idempotency key. - [`documents.comments.resolve`](https://app.getoatmilk.com/docs/api/documents.comments.resolve.md) — Resolve or reopen an agreement-template comment thread with its expected revision. The change is recorded in the audit trail. Requires an idempotency key. ## documents.content - [`documents.content.edit`](https://app.getoatmilk.com/docs/api/documents.content.edit.md) — Edit an agreement template or contractor template in place with 1 to 50 operations applied together, all or nothing: replace_text, delete_text, insert_text (Markdown at the start or end, or before or after the block holding anchor text), place_signature_section (moves it if already placed), insert_page_break, replace_document, set_title, set_description, set_letterhead, set_field (label, required, default), remove_field, set_signers, and for agreements set_footer (up to two lines with merge fields and {{page}} / {{pages}}; null for the default footer), set_logo (a library image, or null for the company logo), insert_image (a library image with alt, width 10–100 percent and align), insert_saved_block (a saved block from documents.snippets.list) and insert_record_details (a record's details from documents.records.search as plain text: lines, values or table, optionally only some fields by key). Text is found by quoting it exactly, though spacing may differ; quote enough to be unique or pass occurrence. Pass expectedRevision to refuse if it changed since you read it; without it, quoted edits apply to the latest version. Anyone with it open in the agreement writer sees the change at once. Starter templates and uploaded files are read-only. Returns the new revision and a line per change. - [`documents.content.get`](https://app.getoatmilk.com/docs/api/documents.content.get.md) — Read a document's text to review or edit it: an agreement template written in the agreement writer (documentType agreement_template) or a contractor agreement template written in Oatmilk (contractor_template). Returns the title, revision, status (draft, published, archived, starter), the Markdown text in pages of up to 20,000 characters (offset and nextOffset), its headings, and for agreements the letterhead setting, merge fields, signers, footer, logo and the library images it places. Agreement Markdown uses {{field.key}} merge fields, a {{signatures}} line for the signature section and a \pagebreak line for a page break. ## documents - [`documents.download`](https://app.getoatmilk.com/docs/api/documents.download.md) — Get a short-lived private link to a kept record's unchanged original file. Pass inline: true to open it in the browser instead of downloading it. - [`documents.extract`](https://app.getoatmilk.com/docs/api/documents.extract.md) — Read a kept record's details again with the extraction model, keeping every field a person edited. Returns the record with extraction pending; poll documents.get for the result. - [`documents.get`](https://app.getoatmilk.com/docs/api/documents.get.md) — Read one kept record by id with its fields, what the rules and the model extracted, the classifier's result and the upload it came from. - [`documents.list`](https://app.getoatmilk.com/docs/api/documents.list.md) — List kept records: tax documents (filed returns and schedules, GST/HST returns, notices of assessment and reassessment, CRA letters, payment confirmations, T4, T4A and T5 slips and summaries), company documents, bank statement PDFs and other records. Filter by kind (tax_document, company_document, bank_statement, other, company, contractor for any record filed with a contractor, or all), contractorId (records filed with one contractor, such as their tax forms and IDs, and invoices they attached to a pay period in the portal), contractorPeriodId (the invoices attached to one pay period), taxYear and search. Each record has its extracted fields, extraction status, contractorId and contractorPeriodId; with kind contractor or contractorId, contractorNames maps each contractor to their name. - [`documents.update`](https://app.getoatmilk.com/docs/api/documents.update.md) — Correct a kept record with id, expectedRevision and idempotencyKey: title, subtype, taxYear, periodStart, periodEnd, documentDate, contractorId, archived, and fields such as form, filedOn, assessedOn, businessNumber, programAccount, balanceOwingMinor, refundMinor, dueDate and referenceNumber. Edited fields are never overwritten by a later extraction. ## documents.history - [`documents.history.get`](https://app.getoatmilk.com/docs/api/documents.history.get.md) — Rebuild one saved version of an agreement template from its history (id from documents.history.list, and firstId to compare with the version before that session): its name, text, footer, letterhead, logo and signers, and the same for the version before. - [`documents.history.list`](https://app.getoatmilk.com/docs/api/documents.history.list.md) — Read an agreement template's history, newest first: sessions of saves (who, when, through the writer, Ask AI, an AI app, the API, an accepted suggestion or a restore, and what changed: text, name, fields, signers, letterhead, footer or logo), publishing and archiving, and suggestions made, accepted or rejected. Pass before (the nextBefore it returned) for older history. - [`documents.history.restore`](https://app.getoatmilk.com/docs/api/documents.history.restore.md) — Restore a saved version of an agreement template as a new change (id from documents.history.list and an idempotencyKey): its text, name, letterhead, footer, logo and signers go back, checked and audited like any edit. Earlier versions stay in the history. ## documents.records - [`documents.records.get`](https://app.getoatmilk.com/docs/api/documents.records.get.md) — Read one record's details as labelled values to put into a document, such as a contractor's or customer's legal name, email, phone and address, a merchant's website, a teammate's name and role, or the company's legal name, address and business number. Pass type and id from documents.records.search (id is "company" for the company). - [`documents.records.search`](https://app.getoatmilk.com/docs/api/documents.records.search.md) — Find a record whose details can go into a document: contractors, customers and vendors (party), merchants, teammates (member) and the company itself. Filter by type and search by name or email. Returns each record's type, id, name and a short description; read its details with documents.records.get. ## documents.snippets - [`documents.snippets.create`](https://app.getoatmilk.com/docs/api/documents.snippets.create.md) — Save a block of Markdown (kind block) or a footer (kind footer, up to 500 characters and two lines) to reuse in agreements, with a title and an idempotencyKey. Insert a saved block into a template with documents.content.edit insert_text. - [`documents.snippets.list`](https://app.getoatmilk.com/docs/api/documents.snippets.list.md) — List saved blocks (reusable clauses and passages in Markdown, which may use {{field.key}} merge fields) and saved footers (up to two lines, which may use merge fields and {{page}} / {{pages}}). Filter by kind block or footer and search titles. - [`documents.snippets.update`](https://app.getoatmilk.com/docs/api/documents.snippets.update.md) — Change a saved block's or footer's title or text, or archive it, with id, expectedRevision and idempotencyKey. Templates that already used it keep their own copy. ## documents.suggestions - [`documents.suggestions.create`](https://app.getoatmilk.com/docs/api/documents.suggestions.create.md) — Suggest changes to an agreement template for a person to review instead of making them: the same operations as documents.content.edit, with a one-line summary of what they do and why, and an idempotencyKey. Nothing changes until a person accepts it in the agreement writer; they can reject it instead. The operations must apply to the template as it is now. Use this when the person asks for suggestions or reviews changes first. - [`documents.suggestions.decide`](https://app.getoatmilk.com/docs/api/documents.suggestions.decide.md) — Accept or reject a suggested change with id, expectedRevision, decision (accept or reject), an optional note and an idempotencyKey. Accepting applies the suggestion to the template as it is now, in the same step as the decision, and is recorded in the audit trail; one that no longer applies can only be rejected. Ask AI can't decide; the person does in the writer. - [`documents.suggestions.list`](https://app.getoatmilk.com/docs/api/documents.suggestions.list.md) — List suggested changes to an agreement template (open ones by default, or all with status all). Each open suggestion includes a preview of what accepting it would do to the template as it is now: the blocks before and after and a line per change, or why it no longer applies. ## signing.envelopes - [`signing.envelopes.certificate`](https://app.getoatmilk.com/docs/api/signing.envelopes.certificate.md) — Render the current certificate and audit trail for an envelope as a PDF (pdfBase64): recipients, verification and signing times, IP addresses, devices, document hashes, and consent text. - [`signing.envelopes.createDraft`](https://app.getoatmilk.com/docs/api/signing.envelopes.createDraft.md) — Create a draft envelope from a template (templateId or templateKey) or an uploaded file (fileId) with title, message, recipients (signer or cc, signerRole, order, userId for a company signer who signs in Oatmilk), mergeValues, signingOrder (parallel or sequential), deadline, and reminder interval. A template that states pay (like the contractor agreement) is made from a job: jobRoleId and jobRoleVersion (a version from contractorOps.roles.versions), and engagement: the pay as rate {amountMinor (minor units, as a string of digits), currency, unit: hour, day, week, month, year or fixed}, basis job (the version's pay: its currency and unit, within its band) or one_off (a rate for this agreement only, with an optional note), and startDate, endDate and noticeDays. The pay, its currency, the role and the dates are then filled in from these and can't be set through mergeValues. Nothing is sent. - [`signing.envelopes.defaults`](https://app.getoatmilk.com/docs/api/signing.envelopes.defaults.md) — Suggested merge values and recipients for a new document from the company profile, the requesting member, and an optional linked contractor or customer. For a contractor it also says what their agreement in effect sets (title, job role and rate) and whether an update to it is waiting (contractor). - [`signing.envelopes.download`](https://app.getoatmilk.com/docs/api/signing.envelopes.download.md) — Get a short-lived private download for an envelope document: the original upload, the signable PDF, or the completed PDF with its certificate of completion. Downloads are recorded in the audit trail. - [`signing.envelopes.get`](https://app.getoatmilk.com/docs/api/signing.envelopes.get.md) — Read one envelope with recipients and their signing status (including links locked after too many incorrect codes), documents (original, signable, completed) with SHA-256 hashes, the most recent audit events newest first (hasOlderEvents tells you to page back with signing.events.list), the email log, the actions available now, and for an agreement made from a job, the job version it used (job.version: what it said and paid then) and where that job is now (job.current: its current version and pay, and whether it's archived), with the agreement's pay in envelope.engagement. - [`signing.envelopes.importExecuted`](https://app.getoatmilk.com/docs/api/signing.envelopes.importExecuted.md) — Record an agreement signed outside Oatmilk: fileId from signing.files.confirm (or googleDocUrl), title, executedOn, parties, optional endsOn and linked record (for example subjectType contractor). The original is kept unchanged with its hash and the envelope is marked completed as the agreement on file. - [`signing.envelopes.keep`](https://app.getoatmilk.com/docs/api/signing.envelopes.keep.md) — Keep an envelope that is waiting on suggested changes as it is: every suggested change is declined with the reply (and optional replies per change), signing resumes where it was, and each person who suggested changes gets the reply with a fresh link. - [`signing.envelopes.list`](https://app.getoatmilk.com/docs/api/signing.envelopes.list.md) — List signature envelopes with their status, linked record, recipients' progress, and key dates. Filter by status (including open and attention), templateKey, subjectType and subjectId (for example contractor), or a title/recipient search. Each envelope says whether it is waiting for your own signature (awaitingMe) and, when it is, gives signUrl: the page where you sign it yourself. Pass awaitingMe: true to list only those. Signing only happens there; agents can't sign for you. An envelope made from a job gives the job's title and version and its pay as the agreement states it (pay, rateBasis job or one_off). counts: true also returns how many envelopes each status filter holds. - [`signing.envelopes.prepare`](https://app.getoatmilk.com/docs/api/signing.envelopes.prepare.md) — Prepare the exact document to be signed: render the template on letterhead, or convert an uploaded Word document, image, text file, or public Google Docs link. Uploaded PDF pages stay intact; senders place signature, initials, date, name, title, or email fields directly on the prepared pages before sending. Stores the PDF privately with its SHA-256 hash and field positions. - [`signing.envelopes.remind`](https://app.getoatmilk.com/docs/api/signing.envelopes.remind.md) — Email a reminder with a fresh link to signers who can sign now. Limited to one manual reminder per 24 hours; automatic reminders follow the envelope's reminder interval until the deadline. - [`signing.envelopes.resend`](https://app.getoatmilk.com/docs/api/signing.envelopes.resend.md) — Send a new link to one waiting signer, revoking earlier links and sessions and resetting their verification-code limits. This also unlocks a link that was locked after too many incorrect codes. Optionally correct the signer's name or email, or extend the deadline with expiresAt. - [`signing.envelopes.retryCompletion`](https://app.getoatmilk.com/docs/api/signing.envelopes.retryCompletion.md) — Retry finalizing an envelope whose completed PDF could not be prepared after 20 automatic attempts, with expectedRevision. Starts a fresh set of attempts right away; the envelope is completed and the completion emails are sent at most once. Recorded in the audit trail. - [`signing.envelopes.revise`](https://app.getoatmilk.com/docs/api/signing.envelopes.revise.md) — Answer the changes signers suggested to an envelope that is waiting on them by sending a revised version: decisions has, for each open request id, a decision per suggested change (accepted, rejected, or noted for a comment), optionally with the wording the sender accepts instead (text) and a reply. Accepted changes go into the agreement's text, a new envelope is prepared and sent to every signer again, and the old one is cancelled as replaced; signatures on it stay in its record. Optional reply to all signers and a new deadline (expiresAt). Requires at least one accepted change. - [`signing.envelopes.send`](https://app.getoatmilk.com/docs/api/signing.envelopes.send.md) — Send a prepared draft for signature. Each signer receives a private link by email (company signers are asked to sign in Oatmilk); copied recipients are notified. Sequential envelopes notify the next signers only when earlier signers finish. A document that states pay needs its structured pay first, and a job it names must still be in use. A contractor agreement sent to a linked contractor records its job, pay and dates as an update to their terms that takes effect once everyone signs; only one update can wait at a time, and a new title needs a title change first. - [`signing.envelopes.signAsMember`](https://app.getoatmilk.com/docs/api/signing.envelopes.signAsMember.md) — Sign as the assigned company signer from a signed-in Oatmilk session (dashboard only, never API keys or agents): consent, typed or drawn signature, name, and title are recorded with the document hash, time, IP address, and device. - [`signing.envelopes.updateDraft`](https://app.getoatmilk.com/docs/api/signing.envelopes.updateDraft.md) — Edit a draft envelope with expectedRevision, including uploaded-document field positions, and its job (jobRoleId with jobRoleVersion, or both null) and engagement (the structured pay and dates, or null). Changing document content, the job or the pay clears the prepared PDF and its field positions; field placement alone keeps the PDF. - [`signing.envelopes.void`](https://app.getoatmilk.com/docs/api/signing.envelopes.void.md) — Void a draft, an envelope that is still collecting signatures, an envelope whose finalizing stopped after its automatic attempts, or an imported executed agreement, with a reason. Signing links stop working and people who were notified receive a short notice. Records are kept. ## signing.events - [`signing.events.list`](https://app.getoatmilk.com/docs/api/signing.events.list.md) — List the audit events of one envelope: created, prepared, sent, email accepted/delivered, viewed, code sent, incorrect code, link locked or unlocked, verified, consented, signed, declined, reminded, resent, voided, expired, finalizing stopped or restarted, completed, downloaded. order oldest (default) pages forward with afterId; order newest pages back from the latest event with beforeId. Returns hasMore. ## signing.files - [`signing.files.confirm`](https://app.getoatmilk.com/docs/api/signing.files.confirm.md) — Confirm an uploaded original by fileId after verifying its size, SHA-256 hash, and file signature. Returns the verified fileId, filename, mimeType, sha256, and sizeBytes for use as an envelope source or executed agreement. - [`signing.files.fromGoogleDocs`](https://app.getoatmilk.com/docs/api/signing.files.fromGoogleDocs.md) — Import a Google Docs document by its docs.google.com link as a verified PDF original. Only documents shared publicly (anyone with the link) can be fetched; otherwise download the document as PDF or Word from Google Docs and upload it. - [`signing.files.prepare`](https://app.getoatmilk.com/docs/api/signing.files.prepare.md) — Prepare a private upload for an agreement original: filename, mimeType (PDF, Word .docx, PNG, JPEG, text, Markdown; legacy .doc, .odt and .rtf are kept as records only), sizeBytes up to 25 MB, sha256, idempotencyKey. Returns fileId and uploadUrl; if alreadyUploaded is true skip the upload and confirm. ## signing.subjects - [`signing.subjects.search`](https://app.getoatmilk.com/docs/api/signing.subjects.search.md) — Search contractors and customers to link to an agreement and prefill the other party's details. ## signing.templates - [`signing.templates.archive`](https://app.getoatmilk.com/docs/api/signing.templates.archive.md) — Archive (archived=true) or restore (archived=false) a template with expectedRevision. Archived templates are hidden from new documents but kept for records. - [`signing.templates.create`](https://app.getoatmilk.com/docs/api/signing.templates.create.md) — Create a custom agreement template from Markdown (body with {{field.key}} merge fields and an optional {{signatures}} block), fields, signerRoles, and letterhead. Set duplicateOf to copy an existing or starter template. It is published and ready to send unless publish is false, which keeps it a draft until signing.templates.publish. Requires an idempotency key. - [`signing.templates.get`](https://app.getoatmilk.com/docs/api/signing.templates.get.md) — Read one agreement template with its Markdown body, merge fields, signer roles, letterhead setting, and revision. - [`signing.templates.list`](https://app.getoatmilk.com/docs/api/signing.templates.list.md) — List agreement templates: the Contractor Agreement, Non-Disclosure Agreement, Signature Request, and Document with Header starters on company letterhead plus custom templates, with merge fields and signer roles. Set includeArchived to include archived templates. - [`signing.templates.preview`](https://app.getoatmilk.com/docs/api/signing.templates.preview.md) — Render a PDF preview of a template (templateId) or unsaved template text (body, fields, signerRoles) with merge values and recipients on the organization letterhead. Returns pdfBase64, the page count, and the labels of required fields that are still empty. Nothing is stored. - [`signing.templates.publish`](https://app.getoatmilk.com/docs/api/signing.templates.publish.md) — Publish a draft template with id and expectedRevision so it can be used to send agreements. Templates saved from the agreement writer stay drafts until someone publishes them, and drafts can't be sent. Publishing a template that is already published changes nothing. - [`signing.templates.update`](https://app.getoatmilk.com/docs/api/signing.templates.update.md) — Edit a custom template with expectedRevision. Starter templates are read-only; duplicate them to customize. Documents already sent keep the exact version they were sent with.