Cover Pages are defined as a YAML document that describes the sections and fields of your agreement. Common Paper renders that definition as a fillable form, a web agreement, a PDF, and a Word export. This article covers every key and input type available to you.

If you're new to Custom Agreements, start with Cover Pages for how to get to the form builder in the first place.

Use an AI assistant to write your YAML

We strongly recommend using an AI assistant like Claude or ChatGPT to write your Cover Page YAML instead of writing it by hand. Give it your existing agreement and it can turn the deal-specific terms into sections and fields in minutes, with the indentation, field keys, and input types already right.

This matters more than it might seem. The form builder rejects an unknown top-level key with an error, but it ignores keys it doesn't recognize inside sections and fields, so a hand-typed mistake there produces no error and no effect. An assistant working from this reference avoids most of those mistakes, and it can fix the rest when you tell it what looks wrong in Form view.

Drafting the YAML in a conversation

To get a good first draft, give your assistant:

Your existing agreement, or a list of the terms you want on the Cover Page
The YAML reference, either by pasting in this article or by pointing it to the custom templates page of the Common Paper API docs, which covers the same keys
Which language should be fixed, which fields senders can change, and which fields the recipient fills in

Here's an example prompt:

Using the Cover Page YAML reference at https://api.commonpaper.com/docs/custom_templates, write a Cover Page YAML definition for the attached agreement. Put the deal-specific terms on the Cover Page as fields: parties, fees, term, liability cap, governing law, and notices. Use fixed fields for language senders shouldn't change, and let the recipient fill in their own legal name and notice address.

Paste the result into the YAML tab, then open Form view to see exactly what senders will see. Review the draft the way you would any agreement: check that every field your Terms reference exists on the Cover Page, and that each default is a value you're comfortable sending.

Creating Cover Pages and Terms through the MCP server or API

If you connect Common Paper to your assistant through our MCP server, the assistant can create your Cover Page and Terms directly in your Common Paper account, not only draft them. The Common Paper API supports the same actions if you'd rather script them. In the MCP server and API, Cover Pages are called custom templates, and Terms are called custom terms.

Through the MCP server or the API, you can:

Create a Cover Page from a YAML definition
Publish a new version of a Cover Page
Create text Terms from markdown, and publish new versions of them
Attach Terms to a Cover Page

NOTE: Terms uploaded as a file can only be created in Common Paper or through the API. The MCP server doesn't accept file uploads.

Each version your assistant publishes becomes current immediately, the same as saving in the editor, so new agreements start using it right away. Existing agreements keep the version they were created from. Ask your assistant to show you the YAML before it publishes anything.

To connect your assistant, see Common Paper and LLMs. To generate an API key, see Using the Common Paper API.

The basic shape

A definition has a title and a list of sections. Each section groups related fields.

title: Consulting Agreement
sections:
  - heading: Services
    fields:
      services_description:
        label: Description of services
        input: textarea
  - heading: Payment
    fields:
      payment_terms:
        label: Payment terms
        input: text
        default: Net 30

Field keys, like services_description, are internal identifiers. They must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Each key must be unique across the whole template.

Every section needs at least one field, unless it is a header or an import section.

Top-level settings

All of these are optional except title.

Key	What it does
`title`	The display name of the agreement, shown as the heading on the agreement, PDF, and Word export. Required.
`terms_label`	Renames the "Cover Page" heading. Use this when your agreement calls its terms something else, like Key Terms, Order Form, or Statement of Work.
`terms_sublabel`	Smaller text under the terms label, shown on the PDF and Word export.
`info_box`	Explanatory text shown in a highlighted box above the Cover Page, like the framework explanation on our standard agreements.
`terms_heading`	A heading row rendered at the top of the terms table, such as "Key Terms".
`terms_subheading`	Smaller text under the terms heading, such as "The key legal terms of this Agreement are as follows:".
`signing_disclaimer`	The sentence above the signature blocks. Defaults to "By signing this Cover Page, each party agrees to enter into the Agreement."
`parties`	Renames the two parties. Takes `sender:` and `recipient:` keys, for example Vendor and Client. Defaults are Provider and Customer. See Sending as the other party below.
`footer`	The footer on PDF and Word exports. Write `{terms_version}` anywhere in it to insert the Terms version number. Without this key the footer is the terms name and version. On a Cover Page with no Terms attached there is no version to insert, so `{terms_version}` resolves to nothing and the default footer is empty.

title: Independent Contractor Agreement
terms_label: Framework Terms
info_box: The Framework Terms have 2 parts...
signing_disclaimer: By signing below, both parties accept.
parties:
  sender: Company
  recipient: Contractor
sections:
  ...

Sending as the other party

parties labels the two sides of the agreement. sender is always your organization, the side that creates and sends the agreement, and recipient is the counterparty you send it to.

Some agreements can be sent by either side. An independent contractor agreement, for example, might be sent by the company hiring the contractor, or by a contractor sending it to a new client. To send a Cover Page from the other side, swap the two values:

parties:
  sender: Contractor
  recipient: Company

Your Terms still refer to each party by the same name, so they don't change. Check the Cover Page itself for anything written from one side's point of view, such as a field marked access: recipient so the counterparty can fill it in, and update it to match.

If your team sends the agreement from both sides, keep one template for each. Open the template's ⋮ menu on the Templates page, choose Duplicate, and change parties in the copy.

Template settings

Five more top-level keys set the template's defaults for sending, the same defaults you can set in the template's settings. Every agreement created from the template starts with these values, and the sender can still change them on the Send a new agreement page.

Key	What it does
`negotiations_allowed`	Whether recipients can propose changes. `true` or `false`.
`sender_last_to_sign`	Controls who signs first after a recipient proposes changes. When this is `true` and you accept the recipient's proposed changes, you can send the agreement back to the recipient to sign first, instead of signing it yourself first. `true` or `false`.
`default_signer_email`	The email address of the person who signs for your side by default. It must belong to an active member of your organization. Choosing someone other than yourself depends on your plan.
`include_message`	Whether the email sent with the agreement includes a message from you. `true` or `false`.
`message`	The text of that message. Used when `include_message` is `true`.

title: Consulting Agreement
negotiations_allowed: true
sender_last_to_sign: false
default_signer_email: [email protected]
include_message: true
message: Please review and sign at your convenience.
sections:
  ...

The true/false keys reject any other value. A default_signer_email that isn't an email address, or that doesn't belong to a member of your organization, is rejected when you save.

Any top-level key that isn't listed in this section or the table above is rejected with the error Unknown key '<key>'.

Sections

Each entry in sections: is one row of the Cover Page, with the heading on the left and its fields on the right.

Key	What it does
`heading`	The section name shown on the left.
`subheading`	Smaller text under the heading.
`required: true`	The section always appears on the agreement and cannot be excluded by the sender.
`included: false`	The section is excluded by default. Senders can include it per agreement with a checkbox when creating the agreement.
`header`	Makes the section a full-width header row instead of a fields row. Use it to divide the Cover Page, for example "Additions and Modifications". A header section can't have fields. Adding any is an error.
`import`	Pulls in a ready-made section. See Imports below.
`access`	Who can edit the section's fields. See Access levels below.

sections:
  - heading: Optional rider
    subheading: Only applies to enterprise deals
    included: false
    fields:
      rider_details:
        label: Rider details
        input: textarea
  - header: Additions and Modifications

Fields

Fields live in a fields: mapping inside a section. The mapping key is the field key, and everything else is configuration.

Key	What it does
`label`	The name shown above the input and next to the value on the agreement.
`input`	The input type. See Input types below. Required.
`instructions`	Guidance shown only on the form while filling it in. It does not appear on the finished agreement.
`placeholder`	Placeholder text inside the empty input.
`required: true`	The field always appears on the agreement, and a value must be entered before the agreement can be sent.
`default`	Prefills the field. Senders can change it when creating an agreement.
`options`	The choices for `radio`, `select`, `multiselect`, and `rate` inputs. Required on all four, and rejected on every other input. A field of one of these types with no options, or only blank ones, is rejected when you save with Field '<key>' must list options.
`currency`	The currency code for `currency` and `rate` inputs. Defaults to USD. Setting it on any other input is an error.
`access`	Who can edit the field. Overrides the section's `access`. See Access levels below.

Fields without a value are left off the finished agreement, unless they are required or fixed.

Input types

Input	Renders as
`text`	Single-line text box
`textarea`	Multi-line text box
`markdown`	Multi-line text box with formatting (bold, lists, links) preserved on the agreement
`number`	Number input
`currency`	Money input with a currency symbol. Commas are added as you type, like 1,000,000, and the amount is saved as a plain number. Set `currency: EUR` to change from USD.
`percent`	Number input with a % sign. Decimals are allowed, up to 6 places. The value must be a number, and it appears with a % sign on the agreement, PDF, and Word export, like 80% or 0.5%.
`rate`	A money amount plus a per-unit select, shown on one line like "$500.00 per hour". `options` lists the units and is required. To send the agreement, a rate needs both an amount and a unit: a required rate isn't complete until both are filled in, and a rate with an amount but no unit is rejected with <Label> needs a unit.
`date`	Date picker
`email`	Email input
`radio`	One choice from `options`, all visible
`select`	One choice from `options`, in a dropdown
`multiselect`	Multiple choices from `options`, shown as checkboxes
`states`	Dropdown of US states
`address`	A full address block. Its parts are `country`, `street_address`, `city`, `state`, and `zip`.
`attachment`	Pick a PDF from your organization's attachment library, or upload a new one. The file is referenced on the agreement and appended to the PDF.
`fixed`	Uneditable text set by `default`. Always appears on the agreement. Use it for standard language that senders should not change.

Two input types take a mapping for their default rather than a single value. Use only the component names listed above as keys, and for rate, a per default has to be one of the field's own options.

fee:
  label: Rate
  input: rate
  options:
    - hour
    - day
  default:
    amount: 500
    per: hour

contractor_address:
  label: Contractor address
  input: address
  default:
    country: USA
    street_address: 100 Main Street
    city: New York
    state: New York
    zip: "10001"

NOTE: address and rate fields expand into one key per component, such as contractor_address_city. Those expanded keys share the same namespace as your regular field keys, so a separate field named contractor_address_city would collide and be rejected.

Access levels

By default only organization admins can edit field values when creating an agreement. Add access to a field or a whole section to open it up.

Value	Who can edit
`admin`	Organization admins only. This is the default.
`standard`	Standard members and admins.
`recipient`	The agreement recipient, plus standard members and admins.

A field-level access overrides its section's. Locked fields show read-only on the form and keep their template defaults.

Recipients are a special case. While negotiation is enabled they can propose changes to any field as before. When negotiation is disabled, access: recipient fields appear as inputs on the recipient's view of the agreement so they can fill them in before signing. Marking one of these fields required: true means the recipient must fill it in before signing. It does not block the sender from sending.

NOTE: attachment fields are the one exception. Recipients can never edit or propose changes to them, because doing so would expose your organization's attachment library. Setting access: recipient on an attachment field has no effect.

sections:
  - heading: Fees
    access: standard
    fields:
      fee:
        label: Monthly fee
        input: currency
      po_number:
        label: PO number
        input: text
        access: recipient

Imports

Imports drop in a ready-made section with one line. You can use each import only once per template. Today there is one import available:

sections:
  - import: governing_law

This renders a Governing Law & Chosen Courts section backed by the same pickers our standard agreements use. To preset answers, add a defaults: mapping. To limit the pickers to specific jurisdictions, add options:.

sections:
  - import: governing_law
    options:
      - New York
      - Delaware
      - California
    defaults:
      governing_law_region: Delaware
      chosen_courts_region: Delaware

The pickers list US states. Organizations allowed to use additional courts also get the same international jurisdictions available on standard agreements, such as England and Wales.

You can also fill the import's inputs in the form preview and switch back to the YAML tab, and the defaults will be written into the YAML for you.

The editor

The template editor has two tabs. The YAML tab is the source of truth. The Form view tab renders your template as the fill-in form a sender will see.

Values you enter in Form view are written back into the YAML as default: values when you switch back. This is a quick way to set defaults without typing YAML, including the mapping syntax for rate and address fields.

Supported input types and import names highlight in the editor as you type, so a typo like input: dropdown stays plain while input: select lights up.

A definition is capped at 100,000 bytes. A misspelled top-level key is rejected with Unknown key '<key>'., but keys the form builder doesn't recognize inside a section or field are ignored rather than rejected, so a misspelling there produces no error and no effect. If something you added isn't showing up, check the spelling against the tables above.

Versions

Every save creates a new version and makes it current immediately. The version dropdown on the edit page lets you load any previous version, and saving while an old version is loaded makes that content the newest version.

Agreements pin the version they were created from, so they always render exactly what the signer saw.

Cover Page YAML Reference